Scripting Guide

Automate Privacy Boost operations with shell scripts and batch processing.

JSON Output

Use --output json (or -o json) for machine-readable output:

# Get all balances as JSON
privacy-boost balances --output json

# Parse with jq
privacy-boost balances -o json | jq '.[] | select(.symbol == "WETH")'

# Get specific field
privacy-boost status -o json | jq -r '.privacy_address'

Environment Setup

Configuration Script

Create a setup script:

#!/bin/bash
# setup-env.sh

export NETWORK="${1:-op-sepolia}"

case $NETWORK in
  op-sepolia)
    export SERVER_URL="https://optimism.sepolia.privacyboost.io"
    export RPC_URL="https://sepolia.optimism.io"
    export WETH_CONTRACT_ADDRESS="0x4200000000000000000000000000000000000006"
    ;;
esac

echo "Environment configured for $NETWORK"

Usage:

source setup-env.sh op-sepolia

Loading the Private Key

The CLI takes the key from one of three places, best first:

Interactive prompt. Leave both --private-key and PRIVATE_KEY unset and the CLI prompts for the key with echo disabled, so it never reaches argv, shell history, or the terminal scrollback. Use this for anything you run by hand. The prompt reads the controlling terminal directly, so it is not available under CI and cannot be fed from a pipe.
PRIVATE_KEY environment variable. The non-interactive fallback. The CLI accepts it and prints a warning at startup.
--private-key on the command line. Avoid it. Arguments are readable by every process on the machine through ps, and they land in shell history and process accounting logs. The flag is hidden from --help for that reason.

None of these encrypt the key at rest. A key kept in a file is a plaintext secret that grants full control of the account, so restrict it to your own user and prefer a real secret store wherever you have one.

#!/bin/bash
# load-key.sh -- source this, do not execute it; it exports PRIVATE_KEY.

# Already provided (CI secret, systemd credential, and so on).
if [ -n "${PRIVATE_KEY:-}" ]; then
  return 0 2>/dev/null || exit 0
fi

# A password manager keeps the key off disk in the clear. Prefer this.
if command -v pass &> /dev/null; then
  PRIVATE_KEY=$(pass show crypto/privacy-boost)
  export PRIVATE_KEY
  return 0 2>/dev/null || exit 0
fi

# Plaintext file fallback. Create it owner-only:
#   mkdir -p ~/.privacy-boost && chmod 700 ~/.privacy-boost
#   touch ~/.privacy-boost/key && chmod 600 ~/.privacy-boost/key
KEY_FILE="${HOME}/.privacy-boost/key"
if [ -f "$KEY_FILE" ]; then
  # Refuse a group- or world-readable key file rather than silently using it.
  PERMS=$(stat -f '%Lp' "$KEY_FILE" 2>/dev/null || stat -c '%a' "$KEY_FILE")
  if [ "$PERMS" != "600" ]; then
    echo "Refusing to read $KEY_FILE: mode $PERMS, want 600" >&2
    return 1 2>/dev/null || exit 1
  fi
  PRIVATE_KEY=$(cat "$KEY_FILE")
  export PRIVATE_KEY
  return 0 2>/dev/null || exit 0
fi

echo "No key available. Run privacy-boost interactively to be prompted." >&2
return 1 2>/dev/null || exit 1

Automation Scripts

Daily Deposit Script

#!/bin/bash
# daily-deposit.sh

set -e

source setup-env.sh mainnet
source load-key.sh

TOKEN="0x4200000000000000000000000000000000000006"  # WETH
AMOUNT="0.1"

# Login
# PRIVATE_KEY is already exported; do not repeat it on the command line.
privacy-boost login

# Check balance
BALANCE=$(privacy-boost balance --token "$TOKEN" --output json | jq -r '.shielded_balance')
echo "Shielded balance: $BALANCE"

# Deposit
echo "Depositing $AMOUNT..."
TX=$(privacy-boost shield --token "$TOKEN" --amount "$AMOUNT" --human --output json | jq -r '.tx_hash')
echo "Deposit TX: $TX"

# Logout
privacy-boost logout

Batch Transfer Script

#!/bin/bash
# batch-transfer.sh

set -e

TRANSFERS_FILE="${1:-transfers.csv}"
TOKEN="0x4200000000000000000000000000000000000006"

# CSV format: privacy_address,amount
# 0x1234...,0.1
# 0x5678...,0.2

source setup-env.sh mainnet
source load-key.sh

# PRIVATE_KEY is already exported; do not repeat it on the command line.
privacy-boost login

# Read and process transfers
while IFS=',' read -r recipient amount; do
  # Skip header or empty lines
  [[ "$recipient" == "privacy_address" ]] && continue
  [[ -z "$recipient" ]] && continue

  echo "Sending $amount to $recipient..."

  TX=$(privacy-boost send \
    --token "$TOKEN" \
    --amount "$amount" \
    --recipient "$recipient" \
    --output json | jq -r '.tx_hash')

  echo "  TX: $TX"

  # Small delay between transactions
  sleep 2
done < "$TRANSFERS_FILE"

privacy-boost logout
echo "Batch complete!"

Monitor Balance Script

#!/bin/bash
# monitor-balance.sh

TOKEN="${1:-0x4200000000000000000000000000000000000006}"
THRESHOLD="${2:-1.0}"
INTERVAL="${3:-300}"  # 5 minutes

source setup-env.sh mainnet
source load-key.sh

# PRIVATE_KEY is already exported; do not repeat it on the command line.
privacy-boost login

while true; do
  BALANCE=$(privacy-boost balance --token "$TOKEN" --output json | jq -r '.shielded_balance')

  TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
  echo "[$TIMESTAMP] Shielded balance: $BALANCE wei"

  sleep "$INTERVAL"
done

Error Handling

Retry Logic

#!/bin/bash
# retry.sh

MAX_RETRIES=3
RETRY_DELAY=5

retry() {
  local n=1
  local cmd="$@"

  until [ $n -gt $MAX_RETRIES ]; do
    echo "Attempt $n: $cmd"
    if eval "$cmd"; then
      return 0
    fi

    echo "Failed, waiting ${RETRY_DELAY}s..."
    sleep $RETRY_DELAY
    ((n++))
  done

  echo "Failed after $MAX_RETRIES attempts"
  return 1
}

# Usage
retry "privacy-boost shield --token $TOKEN --amount 1.0 --human"

Error Notifications

#!/bin/bash
# with-notification.sh

notify_error() {
  local message="$1"

  # Slack webhook
  if [ -n "$SLACK_WEBHOOK" ]; then
    curl -X POST -H 'Content-type: application/json' \
      --data "{\"text\":\"Privacy Boost Error: $message\"}" \
      "$SLACK_WEBHOOK"
  fi

  # Email (using mail command)
  # echo "$message" | mail -s "Privacy Boost Error" admin@example.com
}

# Trap errors
trap 'notify_error "Script failed at line $LINENO"' ERR

# Your operations
privacy-boost shield --token "$TOKEN" --amount 1.0 --human

Cron Jobs

Daily Balance Report

# Run every day at 9 AM
0 9 * * * /path/to/balance-report.sh >> /var/log/privacy-boost.log 2>&1

#!/bin/bash
# balance-report.sh

source /path/to/setup-env.sh mainnet
source /path/to/load-key.sh

# PRIVATE_KEY is already exported; do not repeat it on the command line.
privacy-boost login

echo "=== Daily Balance Report ==="
echo "Date: $(date)"
echo ""
privacy-boost balances

privacy-boost logout

Auto-Deposit on Low Balance

# Check every hour
0 * * * * /path/to/auto-deposit.sh >> /var/log/privacy-boost.log 2>&1

#!/bin/bash
# auto-deposit.sh

MIN_SHIELDED="0.5"  # ETH
DEPOSIT_AMOUNT="1.0"
TOKEN="0x4200000000000000000000000000000000000006"

source /path/to/setup-env.sh mainnet
source /path/to/load-key.sh

# PRIVATE_KEY is already exported; do not repeat it on the command line.
privacy-boost login

BALANCE=$(privacy-boost balance --token "$TOKEN" --output json | jq -r '.shielded_balance')

echo "$(date): Shielded balance: $BALANCE wei"

privacy-boost logout

Integration Examples

With GitHub Actions

# .github/workflows/daily-deposit.yml
name: Daily Deposit

on:
  schedule:
    - cron: '0 9 * * *'
  workflow_dispatch:

jobs:
  deposit:
    runs-on: ubuntu-latest
    steps:
      - name: Download CLI
        run: |
          curl -L https://github.com/sunnyside-io/privacy-boost-sdk/releases/latest/download/privacy-boost-linux-x64.tar.gz | tar xz
          chmod +x privacy-boost

      - name: Run Deposit
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
          SERVER_URL: ${{ vars.SERVER_URL }}
          RPC_URL: ${{ secrets.RPC_URL }}
        run: |
          # The CLI reads PRIVATE_KEY from the environment. Passing it as an
          # argument instead would expose it to `ps` on the runner.
          ./privacy-boost login
          ./privacy-boost shield --token ${{ vars.TOKEN }} --amount 1000000000000000000

Next Steps

Commands Reference - All CLI commands
API Reference - Library API documentation

Quickstart

Setup

SDKs

Scripting

Scripting Guide

JSON Output

Environment Setup

Configuration Script

Loading the Private Key

Automation Scripts

Daily Deposit Script

Batch Transfer Script

Monitor Balance Script

Error Handling

Retry Logic

Error Notifications

Cron Jobs

Daily Balance Report

Auto-Deposit on Low Balance

Integration Examples

With GitHub Actions

Next Steps

​Scripting Guide

​JSON Output

​Environment Setup

​Configuration Script

​Loading the Private Key

​Automation Scripts

​Daily Deposit Script

​Batch Transfer Script

​Monitor Balance Script

​Error Handling

​Retry Logic

​Error Notifications

​Cron Jobs

​Daily Balance Report

​Auto-Deposit on Low Balance

​Integration Examples

​With GitHub Actions

​Next Steps

Scripting Guide

JSON Output

Environment Setup

Configuration Script

Loading the Private Key

Automation Scripts

Daily Deposit Script

Batch Transfer Script

Monitor Balance Script

Error Handling

Retry Logic

Error Notifications

Cron Jobs

Daily Balance Report

Auto-Deposit on Low Balance

Integration Examples

With GitHub Actions

Next Steps