Commands Reference

Complete reference for all Privacy Boost CLI commands.

Global Options

Available for all commands:

privacy-boost [OPTIONS] <COMMAND>
privacy-boost <COMMAND> [OPTIONS]

Options:
  -n, --network <PRESET>       Network preset (local, op-sepolia)
  -c, --config <FILE>          Configuration file path
  -k, --private-key <KEY>      Private key (hex string, with or without 0x prefix)
      --server-url <URL>               Server URL (overrides config)
      --rpc-url <URL>                  RPC URL (overrides config)
      --chain-id <ID>                  Chain ID (overrides config)
      --shield-contract-address <ADDR> Shield contract address (overrides config)
      --weth-contract-address <ADDR>   WETH contract address (overrides config)
  -o, --output <FORMAT>        Output format: json, text (default: text)
  -h, --help                   Print help
  -V, --version                Print version

Configuration Commands

init

Initialize a configuration file at ~/.privacy-boost/config.toml.

privacy-boost init [OPTIONS]

Options:

-n, --network <PRESET> - Network preset to use (default: local)

If a config file already exists, the command prints a warning and does nothing. Delete the existing file first to reinitialize. You can also import an existing config file:

privacy-boost init --config /path/to/my-config.toml

Examples:

# Initialize with local dev defaults
privacy-boost init

# Initialize with OP Sepolia preset
privacy-boost init --network op-sepolia

# Import an existing config as the default
privacy-boost init --config ~/my-project-config.toml

Authentication Commands

Connect wallet, derive privacy keys, and authenticate with the backend. Saves the session so future commands don’t require --private-key.

privacy-boost login --private-key <KEY>

Examples:

# Using flag
privacy-boost login --private-key 0x...

# Using environment variable
export PRIVATE_KEY="0x..."
privacy-boost login

Output:

Logged in!
  Wallet Address:  0x1234...5678
  Privacy Address: 0x9abc...def0
  MPK:             0xfedc...ba98

Session saved! Future commands won't require --private-key.

logout

Clear saved session.

privacy-boost logout

sessions

List saved sessions and their expiry status.

privacy-boost sessions

status

Show current connection and authentication status.

privacy-boost status

Output:

Status
  Connected:     Yes
  Authenticated: Yes
  Wallet Address:  0x1234...5678
  Privacy Address: 0x9abc...def0

Balance Commands

balance

Query shielded balance for a specific token.

privacy-boost balance --token <ADDRESS>

Options:

-t, --token <ADDRESS> - Token contract address (use 0x0 for ETH)

Examples:

privacy-boost balance --token 0x4200000000000000000000000000000000000006

balances

Query all token balances.

privacy-boost balances

Vault Commands

shield

Deposit tokens into the shielded pool.

privacy-boost shield [OPTIONS]

Options:

-t, --token <ADDRESS> - Token contract address (required)
-a, --amount <VALUE> - Amount in wei
--human - Parse amount as human-readable (e.g., 1.5 instead of wei)
--decimals <N> - Decimals for human-readable parsing (default: 18)

Examples:

# Deposit in wei
privacy-boost shield --token $WETH --amount 1000000000000000000

# Deposit in human-readable format
privacy-boost shield --token $WETH --amount 1.0 --human

unshield

Withdraw tokens from the shielded pool to a public address.

privacy-boost unshield [OPTIONS]

Options:

-t, --token <ADDRESS> - Token contract address (required)
-a, --amount <VALUE> - Amount in wei
-r, --recipient <ADDRESS> - Recipient Ethereum address (required)
--human - Parse amount as human-readable
--decimals <N> - Decimals for human-readable parsing (default: 18)

Examples:

privacy-boost unshield \
  --token $WETH \
  --amount 0.5 \
  --recipient 0x1234... \
  --human

send

Send a private transfer to a privacy address or Ethereum address.

privacy-boost send [OPTIONS]

Options:

-t, --token <ADDRESS> - Token contract address (required)
-a, --amount <VALUE> - Amount in wei
-r, --recipient <ADDRESS> - Recipient privacy address (194 chars) or Ethereum address (42 chars)
--human - Parse amount as human-readable
--decimals <N> - Decimals for human-readable parsing (default: 18)

Examples:

privacy-boost send \
  --token $WETH \
  --amount 0.1 \
  --recipient 0x[194-char-privacy-address] \
  --human

prepare-shield

Build a deposit payload without submitting it, for relaying the transaction yourself (a gasless relayer, an EIP-7702 session key, or a plain raw transaction). Prints the wrap/approve/requestDeposit calls plus the note commitment; nothing is sent on-chain. Requires authentication (login first, or pass --private-key). After relaying, settle it with finalize-shield.

privacy-boost prepare-shield [OPTIONS]

Options:

-t, --token <ADDRESS> - Token contract address (use 0x0 for ETH) (required)
-a, --amount <VALUE> - Amount in wei
-r, --recipient <ADDRESS> - Recipient privacy address (omit to shield to yourself)
--human - Parse amount as human-readable
--decimals <N> - Decimals for human-readable parsing (default: 18)

Examples:

# Prepare a self-shield and print the payload as JSON
privacy-boost prepare-shield --token $WETH --amount 1.0 --human --output json

# Prepare a deposit targeted at another user's privacy address
privacy-boost prepare-shield \
  --token $WETH \
  --amount 1000000000000000000 \
  --recipient 0x[194-char-privacy-address]

With --output json the full PreparedShield is printed (the approve, wrap, and shield calls, each as { to, value, data }, plus commitment and finalize), ready to feed into a relayer.

finalize-shield

Recover the on-chain shield request id from the mined receipt of a relayed deposit (see prepare-shield). Stateless — no authentication required.

privacy-boost finalize-shield [OPTIONS]

Options:

--receipt <JSON> - Mined receipt as inline JSON {transactionHash,status,logs:[{address,topics,data}]}, or @path to a file (required)
--commitment <0x..> - Commitment from the prepared shield being settled (required)
--shield-contract <ADDRESS> - Shield pool contract (defaults to --shield-contract-address)

Examples:

# Finalize from a receipt file
privacy-boost finalize-shield \
  --receipt @receipt.json \
  --commitment 0xabcd...ef01

# Finalize from inline receipt JSON, with explicit shield contract
privacy-boost finalize-shield \
  --receipt '{"transactionHash":"0x...","status":true,"logs":[...]}' \
  --commitment 0xabcd...ef01 \
  --shield-contract 0x1234...

History Commands

history

View transaction history.

privacy-boost history [OPTIONS]

Options:

-t, --tx-type <TYPE> - Filter by type (shield, unshield, transact)
--token <ADDRESS> - Filter by token address
-l, --limit <N> - Maximum number of results

Examples:

# All transactions
privacy-boost history

# Deposits only
privacy-boost history --tx-type shield

# JSON output with limit
privacy-boost history --limit 10 --output json

Utility Commands

resolve-identity

Look up a user’s identity by Ethereum address or MPK.

privacy-boost resolve-identity <IDENTIFIER>

Arguments:

<IDENTIFIER> - Ethereum address (42 chars) or MPK (66 chars)

Examples:

privacy-boost resolve-identity 0x1234567890123456789012345678901234567890

version

Show version information.

privacy-boost version

Gift Commands

Claimable transfers — send to an unregistered wallet. Preview feature, pending external audit.

gift-fund-to-wallet

Fund a gift bound to a wallet that has not joined Privacy Boost.

privacy-boost gift-fund-to-wallet [OPTIONS]

Options:

-t, --token <ADDRESS> - Token contract address (required)
-a, --amount <VALUE> - Amount in wei (or decimal with --human)
--recipient-wallet <ADDRESS> - Recipient Ethereum address the gift binds to
--refund-after-block <N> - Block after which you may reclaim an unclaimed gift
--current-block <N> - Current chain head (pre-validates the refund delay)
--human - Parse amount as human-readable
--yes - Skip the recipient-wallet confirmation prompt

gift-fund

Like gift-fund-to-wallet, but also takes the recipient’s privacy address (-r, --recipient) so the gift ciphertext is sealed to their viewing key.

gift-list

List the claimable (pending) gifts addressed to your wallet.

privacy-boost gift-list

gift-claim

Claim a pending gift by its index in gift-list.

privacy-boost gift-claim --index 0 --acknowledge-unknown-sender

--acknowledge-unknown-sender is required — the sender is hidden, so you explicitly accept funds from an unknown source.

gift-claim-from-link

Claim directly from an out-of-band claim link.

privacy-boost gift-claim-from-link --link pbgift:v1:... --acknowledge-unknown-sender

gift-refund-by-record

Reclaim a gift you funded that went unclaimed, by its index in your local gift ledger (persisted in your session file).

privacy-boost gift-refund-by-record --index 0

gift-refund

Reclaim an unclaimed gift by supplying every field manually (when you no longer have the local record): --recipient-wallet, --blind, --refund-after-block, --token-id, --amount, --tree-number, --leaf-index.

gift-decode-link

Decode and decrypt a claim link into a preview, with no network call.

privacy-boost gift-decode-link --link pbgift:v1:...

Portal Commands

Portal deposit addresses — reusable public deposit addresses. Preview feature, pending external audit. All require an authenticated session.

portal create

Derive a portal address E, delegate it, register, and publish — in one call.

privacy-boost portal create [--index <N>] [--no-publish]

portal list

List your portals.

privacy-boost portal list

portal status

Show the registered / delegated / published status of a portal. (delegated always reports false at launch.)

privacy-boost portal status <PORTAL_ADDRESS>

portal deposits

List the deposits observed at a portal.

privacy-boost portal deposits <PORTAL_ADDRESS>

portal sweep

Self-service sweep backstop (operator-run at launch): sweep a token’s balance at the portal into the pool.

privacy-boost portal sweep <PORTAL_ADDRESS> <TOKEN_ID>

portal reclaim

Reclaim an un-credited deposit after the cancel delay; funds return to the portal.

privacy-boost portal reclaim <PORTAL_DEPOSIT_ID>

portal withdraw

Build a signed raw EIP-1559 tx that withdraws funds resting at E (escape hatch); prints the raw tx to broadcast yourself.

privacy-boost portal withdraw <INDEX> <TOKEN> <TO> <AMOUNT> <NONCE> <GAS_LIMIT> <MAX_FEE_PER_GAS> <MAX_PRIORITY_FEE_PER_GAS>

Environment Variables

Variable	Description
`PRIVATE_KEY`	Wallet private key
`SERVER_URL`	Privacy Boost server URL
`RPC_URL`	RPC URL
`WETH_CONTRACT_ADDRESS`	WETH contract address
`SHIELD_CONTRACT_ADDRESS`	Shield contract address (auto-discovered if omitted)
`PRIVACY_BOOST_APP_ID` or `APP_ID`	App ID for multi-tenant auth
`PRIVACY_BOOST_TEE_PUBLIC_KEY` or `TEE_PUBLIC_KEY`	TEE public key for deposit encryption

Next Steps

Network Presets - Network configuration
Scripting Guide - Automation examples
API Reference - Library API documentation

​Commands Reference

​Global Options

​Configuration Commands

​init

​Authentication Commands

​login

​logout

​sessions

​status

​Balance Commands

​balance

​balances

​Vault Commands

​shield

​unshield

​send

​prepare-shield

​finalize-shield

​History Commands

​history

​Utility Commands

​resolve-identity

​version

​Gift Commands

​gift-fund-to-wallet

​gift-fund

​gift-list

​gift-claim

​gift-claim-from-link

​gift-refund-by-record

​gift-refund

​gift-decode-link

​Portal Commands

​portal create

​portal list

​portal status

​portal deposits

​portal sweep

​portal reclaim

​portal withdraw

​Environment Variables

​Next Steps

Commands Reference

Global Options

Configuration Commands

init

Authentication Commands

login

logout

sessions

status

Balance Commands

balance

balances

Vault Commands

shield

unshield

send

prepare-shield

finalize-shield

History Commands

history

Utility Commands

resolve-identity

version

Gift Commands

gift-fund-to-wallet

gift-fund

gift-list

gift-claim

gift-claim-from-link

gift-refund-by-record

gift-refund

gift-decode-link

Portal Commands

portal create

portal list

portal status

portal deposits

portal sweep

portal reclaim

portal withdraw

Environment Variables

Next Steps