CLI Reference

shade is the reference command-line tool and the fastest way to run the whole flow. Install it with npm install -g stellar-shade-cli. Seven commands: keygen, address, send, scan, balance, claim, withdraw.

Conventions

Secrets. Every secret resolves in this order: inline flag, then environment variable, then a non-echoing stderr prompt. Flags exist for scripting but leak into shell history and ps output, so prefer the env var or the prompt.

Prompts fail loudly without stdin. If stdin closes before a prompt is answered (piped input, CI), the command exits 1 with stdin closed before input was received — pass the value via its flag or environment variable instead. In non-interactive contexts, supply every needed value via its flag or env var.

Keystore path resolves as: --keystore <path> → $SHADE_KEYSTORE → ~/.shade-keys.json.

Relayers. --relay (on claim and withdraw) is repeatable and comma-separated: --relay https://a,https://b and --relay https://a --relay https://b both work. It falls back to the comma-separated SHADE_RELAYERS env var when omitted. With more than one URL the client health-probes all candidates in parallel, routes to a healthy one (random by default, spreading users across the set), and fails over on relayer faults. --verbose prints the chosen relayer. When none is usable, the error lists every candidate with its rejection reason. See Relayer → Choosing a relayer.

Indexer. --indexer <url> (on scan and balance) points account-method discovery at an announcement indexer and falls back to the SHADE_INDEXER env var when omitted (flag wins; a single URL, no list). Horizon remains the source of truth: the scan verifies the indexer’s health first, always finishes with a Horizon tail, and degrades silently to the plain Horizon walk on any indexer fault. scan --verbose reports the indexer in use.

Networks: --network testnet is the default and the only accepted value today. Anything else, notably the removed local and the not-yet-audited mainnet, is rejected with an error. Mainnet (“public”) arrives after the external audit.

shade keygen

Generate or recover stealth keys and write a keystore. Prints your meta-address.

shade keygen                              # random keys; keystore ENCRYPTED by default
shade keygen --mnemonic                   # new BIP-39 mnemonic (enables recovery)
shade keygen --recover                    # recover from an existing 12-word mnemonic
shade keygen --from-stellar-secret        # derive deterministically from a Stellar secret
shade keygen --plaintext                  # opt OUT of encryption
shade keygen --force                      # required to OVERWRITE an existing keystore

Keygen refuses to overwrite. If a keystore already exists at the target path, keygen exits with an error rather than clobbering it: overwriting destroys the old spend/view keys, and with them access to any unclaimed funds sent to the old meta-address. Either write elsewhere with --keystore <path>, re-display the existing meta-address with shade address, or pass --force if you really mean to overwrite.

Encryption is the default. A plaintext keystore is written only when you explicitly opt out with --plaintext / --no-encrypt. Combining --plaintext with --password is an error, and an empty password is rejected.

shade address

Re-display the meta-address of an existing keystore. No password needed: both the plaintext and encrypted envelopes store the spend/view public keys in the clear, and the meta-address derives purely from them.

shade address                             # prints shade:stellar:...

This is the safe answer to “I lost my meta-address,” as opposed to re-running shade keygen, which would overwrite the keys (and refuses to without --force).

shade send

Send to a stealth address derived from a meta-address.

shade send <meta-address> <amount> --method auto --network testnet
shade send <meta-address> 100 --method pool
shade send <meta-address> 200 --method account --asset USDC:GISSUER

A method is mandatory. auto resolves to account for native XLM above 1 XLM, otherwise pool.

The amount is parsed to exact stroops before any float math, so more than 7 decimal places or an out-of-range value is rejected up front rather than drifting.

shade scan

Find payments sent to you, across both the pool and account methods.

shade scan --network testnet
shade scan --indexer http://localhost:3100
shade scan --full-rescan

Cursors. The account method persists a Horizon paging cursor and its discovered payments to ~/.stealth/, so a later claim can resolve a payment without a full rescan. --full-rescan clears both, and, with an indexer configured, additionally walks the pre-indexer history: a cold scan otherwise fast-starts at the indexer’s coverage start, so a payment predating that coverage is found only by --full-rescan. See Architecture → The announcement indexer.

shade balance

Show your total balance across all discovered stealth payments.

shade balance --network testnet

Balances are aggregated per token in stroops and displayed with a readable asset label (XLM rather than the native SAC C... address).

shade claim

Claim a discovered payment to a destination address. This is the preferred, unified command: it handles both pool and account payments.

shade claim <stealth-addr> <destination> --fee-payer S...                    # pool withdraw
shade claim <stealth-addr> <destination> --relay http://localhost:3000       # account sweep
shade claim <stealth-addr> <destination> --sponsored --funding-account G...  # token, no reserves

# Against a credit-gated relayer (the default), the funding account must also
# SIGN the relayer's challenge: supply its secret (prefer the env var):
SHADE_FUNDING_SECRET=S... shade claim <stealth-addr> <destination> \
  --relay https://relayer.example --funding-account G...

The funding secret alone is enough: the account is derived from it, and passing both asserts they match. Without a signer, a credit-gated relayer rejects the request (401 missing_auth).

How it routes: claim looks the stealth address up in the persisted account-method payment cache. A hit takes the account path; a miss is assumed to be a pool deposit and runs the same pool-withdraw path as withdraw.

shade withdraw

Direct pool withdrawal. Deprecated: claim is the preferred unified command and routes pool payments through this same path. withdraw remains for the explicit pool case and for scripts that already use it.

shade withdraw <stealth-addr> <destination> --fee-payer S... --asset USDC:GISSUER

A fee payer is required. If the recipient’s pool entry has archived, the CLI transparently submits a RestoreFootprintOp first and rebuilds the withdraw on a fresh sequence.

Local state

The CLI keeps state under ~/.stealth/:

The keystore itself defaults to ~/.shade-keys.json.

Next steps

• Getting Started: install and first run
• Delivery Methods: what --method actually changes
• SDK Reference: the programmatic equivalent
• FAQ & Troubleshooting: common command failures