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, op-mainnet, base-mainnet, base-sepolia, soneium-mainnet, ink-mainnet)
  -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

fees

Query the ordinary fee schedule for a registered token ID, or bind the quote to an ExternalCallGateway address and optional 4-byte calldata selector.

privacy-boost fees <TOKEN_ID>
privacy-boost fees <TOKEN_ID> --gateway-address <ADDRESS> [--gateway-selector <0xSELECTOR>]

--gateway-selector requires --gateway-address. An exact selector policy is used when configured; otherwise the Gateway-wide default applies.

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

send-batch

Send one private transfer paying several recipients: one request, one fee, one set of input notes.

privacy-boost send-batch [OPTIONS]

Options:

-t, --token <ADDRESS> - Token contract address (required)
--to <RECIPIENT:AMOUNT> - Recipient and amount, repeatable (required). Recipient is a privacy address (194 chars) or an Ethereum address (42 chars)
--human - Parse amounts as human-readable
--decimals <N> - Decimals for human-readable parsing (default: 18)

Examples:

privacy-boost send-batch \
  --token $WETH \
  --to 0x[194-char-privacy-address]:0.1 \
  --to 0x[194-char-privacy-address]:0.25 \
  --human

The transfer’s output count is the recipient count plus a change note, and the server only proves specific (inputs, outputs) combinations, so past two recipients at most four input notes can be spent. A batch that can’t be proven fails with UNSUPPORTED_TRANSFER_SHAPE; run consolidate first, or split the payout.

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 your wallet private key (--private-key, PRIVATE_KEY, or the prompt): the commitment is built from your keys, which a saved login session keeps locked. 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-id <ID> - Only rows for this registry token id
--direction <DIRECTION> - Only incoming or outgoing rows, relative to this wallet
-l, --limit <N> - Maximum number of results
--collapse-gateway - Show each Gateway operation as one row instead of its two epochs

Examples:

# All transactions
privacy-boost history

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

# Outgoing rows for token id 1, as JSON
privacy-boost history --token-id 1 --direction outgoing --output json

# 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.

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:...

Deposit Commands

Inspect or reclaim a shield deposit still escrowed in the pool. A shield holds your tokens in the pool until the sequencer settles the request into the note tree; when settlement never happens, these two commands get them back. Both read the pool directly, because nothing server-side describes the escrow behind a shield that didn’t settle, and both require an authenticated session. Only the address that submitted the deposit can cancel it, and the refund goes to that address. For a relayer-submitted shield that’s the relayer, not the note recipient. A deposit that entered through the gateway has the gateway contract as its depositor, so no wallet can cancel it — those report GatewayOrigin and have to go through rescueGatewayDeposit.

deposit list

Find a deposit request id you never kept. Lists your own shields by status, oldest first.

privacy-boost deposit list --status failed

--status takes a comma-separated list of public statuses (pending, processing, preconfirmed, completed, failed) and defaults to pending. failed is the recovery entry point — those are the shields whose escrow may still be sitting in the pool. Text output prints requestId<TAB>status per row; --output json prints the full records including txHash and blockNumber. failed also covers shields the server rejected as below-minimum or blocked, which it folds into the same public status. A stalled sequencer produces no failed row at all, so a sweep for everything unsettled wants --status pending,failed.

deposit ids

Recover the deposit request ids a shield transaction emitted, for when you kept the transaction hash but not the request id.

privacy-boost deposit ids <TX_HASH>

Prints one id per line, in log order. More than one appears when an aggregating relayer settled several callers’ deposits in the same transaction. No output means the transaction emitted no DepositRequested from the pool, which is the answer for a hash that was never a shield.

deposit status

Show whether a pending deposit can be cancelled, and why not if it can’t. Prints the reason line, plus the target block and countdown while the cancel delay is still running. --output json prints the full status: state, cancellable, totalAmount, cancelDelay, cancellableAtBlock, blocksRemaining, and more.

privacy-boost deposit status <DEPOSIT_REQUEST_ID>

DEPOSIT_REQUEST_ID is the depositRequestId from the DepositRequested log, decimal or 0x-hex. The cancel delay is measured in blocks and read from the pool’s cancelDelay(). Read it from the command’s output rather than hardcoding a delay.

deposit cancel

Cancel a pending deposit, refunding its full escrow to the original depositor. Prints the transaction hash.

privacy-boost deposit cancel <DEPOSIT_REQUEST_ID>

The command runs the deposit status checks first and fails locally, before anything is signed, when the pool would revert, so a deposit that can’t be cancelled tells you why instead of costing gas on an opaque revert. A deposit that entered through the gateway can’t be cancelled at all; it has to be recovered with rescueGatewayDeposit by its rescue authority.

Portal Commands

Portal deposit addresses — reusable public deposit addresses. 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. Without pagination options, the CLI accumulates pages within the SDK safety cap. Supplying either option fetches one page and prints the opaque next_cursor when another page is available.

privacy-boost portal list [--cursor <CURSOR>] [--limit <1-100>]

portal status

Show the registered / delegated / published status of a portal.

privacy-boost portal status <PORTAL_ADDRESS>

portal deposits

List the deposits observed at a portal. Pagination options have the same one-page behavior as portal list.

privacy-boost portal deposits <PORTAL_ADDRESS> [--cursor <CURSOR>] [--limit <1-100>]

portal sweep

Self-service sweep backstop, since a keeper normally handles this: 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>

Earn Commands

Earn (ERC-4626 vaults) — move a shielded balance into a yield vault and back through the external call gateway. V2 feature, enabled per deployment. vaults and history are public reads. deposit, withdraw, and status require an authenticated session.

earn vaults

List the earn vault catalog (APY, TVL, per-operation availability).

privacy-boost earn vaults

earn deposit

Deposit assets into a vault: spends an asset note, credits a vault-share note. --amount is net — exactly what enters the vault; the Gateway fee replaces the regular unshield fee and is charged on top.

privacy-boost earn deposit --vault <VAULT> --amount <AMOUNT> [--human --decimals <N>] [--slippage-bps <BPS>]

earn withdraw

Withdraw from a vault: redeems share notes, credits an asset note. --amount is the share amount to redeem.

privacy-boost earn withdraw --vault <VAULT> --amount <AMOUNT> [--human --decimals <N>] [--slippage-bps <BPS>]

earn status

Show an earn request’s status, including the gateway settlement and credit projection. creditStatus=completed means private credit succeeded, while creditStatus=rescued means escrow was paid to the rescue destination. Both end the wait for private credit.

privacy-boost earn status <REQUEST_ID>

earn history

One vault’s TVL and/or net-APY history series (chart data; public read). APY values are decimal ratios (0.05 = 5%). Omit --metric to fetch both series concurrently. --period is 1w, 1m, 3m, or all (default 1w).

privacy-boost earn history --vault <VAULT> [--metric tvlUsd|netApy] [--period 1w|1m|3m|all]

Contacts Commands

A private address book. Contacts are stored encrypted per wallet on the server; they never touch keys or notes, so every command here runs on a saved session (login first, or pass --private-key). Text output prints one line per contact; --output json prints the server records with camelCase fields. A contact the server can no longer decrypt is still listed, flagged decryptionFailed, rather than dropped.

contacts list

List contacts, newest first. --limit and --cursor page through the list; the opaque next_cursor is printed when another page exists.

privacy-boost contacts list [--limit <N>] [--cursor <CURSOR>]

contacts create

Create a contact. The privacy address must be unique per wallet. --metadata is repeatable and takes key=value pairs; a repeated key is rejected. --correlation-id is stored as the contact’s clientId; it is deliberately not called --client-id, which is the global api_secret auth flag.

privacy-boost contacts create \
  --privacy-address <PRIVACY_ADDRESS> \
  --nickname <NAME> \
  [--eth-address <ADDRESS>] [--emoji <EMOJI>] [--correlation-id <ID>] \
  [--metadata key=value ...]

contacts update

Patch a contact by id. Only the flags you pass change. --eth-address and --metadata replace the stored value; --clear-eth-address and --clear-metadata remove it. Each pair is mutually exclusive, and at least one flag is required.

privacy-boost contacts update <ID> \
  [--nickname <NAME>] [--emoji <EMOJI>] \
  [--eth-address <ADDRESS> | --clear-eth-address] \
  [--metadata key=value ... | --clear-metadata]

contacts delete

Delete a contact. Labels that referenced it keep their other fields.

privacy-boost contacts delete <ID>

contacts import

Bulk-create contacts from a JSON file holding an array of contact objects in the server’s request shape:

[
  { "privacyAddress": "0x...", "nickname": "Alice", "emoji": "🦊" },
  { "privacyAddress": "0x...", "nickname": "Bob", "ethAddress": "0x...", "clientId": "row-2",
    "metadata": { "team": "ops" } }
]

privacy-boost contacts import --file contacts.json

An entry whose privacy address already exists is reported as skipped with the existing contact’s id, not as an error. clientId is echoed back per row so a script can match results to its input.

Labels Commands

Private memos and contact links keyed by transaction hash. Same storage and session model as contacts.

labels list

privacy-boost labels list [--limit <N>] [--cursor <CURSOR>]

labels set

Create or replace the label on a transaction hash. A label is replaced whole, so any field you omit is cleared on an existing label.

privacy-boost labels set <TX_HASH> [--contact-id <ID>] [--memo <TEXT>] [--metadata key=value ...]

labels delete

privacy-boost labels delete <TX_HASH>

Campaign Commands

campaign progress

Startale mission progress for the authenticated user and app: whether at least $10 has been shielded and whether a transfer has been made. There is no user argument; the server reads the user from the session.

privacy-boost campaign progress

The deposit mission is priced against current token prices at query time, so it can flip back to false; anything that awards on it should record the first true. campaignTokenId is absent when no campaign token is configured, in which case every shielded token counted toward the deposit total.

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

​fees

​Vault Commands

​shield

​unshield

​send

​send-batch

​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

​Deposit Commands

​deposit list

​deposit ids

​deposit status

​deposit cancel

​Portal Commands

​portal create

​portal list

​portal status

​portal deposits

​portal sweep

​portal reclaim

​portal withdraw

​Earn Commands

​earn vaults

​earn deposit

​earn withdraw

​earn status

​earn history

​Contacts Commands

​contacts list

​contacts create

​contacts update

​contacts delete

​contacts import

​Labels Commands

​labels list

​labels set

​labels delete

​Campaign Commands

​campaign progress

​Environment Variables

​Next Steps

Commands Reference

Global Options

Configuration Commands

init

Authentication Commands

login

logout

sessions

status

Balance Commands

balance

balances

fees

Vault Commands

shield

unshield

send

send-batch

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

Deposit Commands

deposit list

deposit ids

deposit status

deposit cancel

Portal Commands

portal create

portal list

portal status

portal deposits

portal sweep

portal reclaim

portal withdraw

Earn Commands

earn vaults

earn deposit

earn withdraw

earn status

earn history

Contacts Commands

contacts list

contacts create

contacts update

contacts delete

contacts import

Labels Commands

labels list

labels set

labels delete

Campaign Commands

campaign progress

Environment Variables

Next Steps