CLI reference

The sats CLI manages one sealed seed and a watch-only wallet per Bitcoin network. Run sats --help or sats <command> --help for the exact option list supported by the installed version.

Quickstart

sats init
sats receive
# Fund the printed address from a signet faucet, then:
sats balance
sats send tb1p... 25k
sats status

Signet is the default. init prints the new mnemonic once; back it up before continuing. Mainnet requires --network mainnet explicitly.

Commands

Everyday commands express intent; the psbt, tx, and agent namespaces hold the explicit advanced workflows.

Global flags

Global flags select the environment for one invocation:

SATS_DIR relocates configuration and data under one directory. The corresponding --dir flag exists for internal/testing use and is hidden from help. SATS_PASSWORD supplies the wallet password non-interactively; avoid putting it in shell history or process-inspection surfaces.

Amounts

Amounts are integer satoshis. Case-insensitive suffixes are accepted:

• 25k = 25,000 sats;
• 1.5m = 1,500,000 sats.

Fractional shorthand must resolve to a whole satoshi. Plain values such as 25000 are interpreted directly as sats.

Sending

sats send <address> <amount> [--fee-rate <SAT_VB>] \
  [--allow-dust] [--no-guards] [--yes | --dry-run | --export-psbt <FILE>]

Every send — human or agent — runs the shared preparation path:

1. validates the address against the selected network;
2. syncs the watch-only wallet;
3. excludes common inscription postage outputs unless --allow-dust;
4. queries and unions configured guards unless --no-guards;
5. estimates a roughly two-block fee unless --fee-rate is supplied;
6. builds the unsigned PSBT in memory.

Sync or configured-guard failure stops preparation. Both bypass flags apply only to the current human invocation and are intentionally absent from MCP sends.

The three send modes:

• Default: shows the priced spend, asks for confirmation, signs, privately persists raw finalized transaction hex, then broadcasts. --yes skips the confirmation prompt but does not bypass UTXO safety, provider validation, password unlocking, or any agent authorization rule.
• --dry-run: prints or returns the priced spend and persists nothing — no PSBT, no transaction record, no wallet-state change, and no password prompt.
• --export-psbt <FILE>: writes the unsigned PSBT to FILE as an owner-only artifact and signs nothing. The change address it reserves is persisted so the artifact stays valid.

If broadcast fails after signing, the transaction is already saved: sats status lists it and sats tx broadcast <txid> retries it.

Transaction visibility

sats status                # pending (signed, unbroadcast) + broadcast with confirmations
sats status <txid>         # one transaction by txid, unique prefix, or session id
sats history               # every wallet transaction, unconfirmed first

Both commands sync first and tolerate sync failure with a stderr warning; --offline skips sync entirely. status <txid> falls back to the wallet's canonical chain view for transactions the store never saw, such as incoming payments.

Explicit PSBT workflow

Normal send never persists a PSBT. The staged lifecycle works on explicit file artifacts:

sats send tb1p... 25k --export-psbt spend.psbt
sats psbt inspect spend.psbt
sats psbt sign spend.psbt
sats tx broadcast <txid>

psbt sign FILE accepts base64 text or binary. When the wallet's signature finalizes the transaction, sats privately saves raw finalized transaction hex (ready for sats tx broadcast); it does not retain the signed PSBT. A PSBT that still needs other signers is written back beside the input as <name>.signed.psbt and reported as partially signed. --out <FILE> always writes the signed PSBT to FILE and persists nothing — the pure artifact path for multi-signer flows.

psbt sign --session <id> signs a stored PSBT session or pre-refactor plan from an older release. The id is always explicit: signing never consumes hidden internal state. New sats versions no longer write stored sessions.

tx broadcast takes exactly one target: an existing file is read as raw transaction hex; anything else resolves a saved transaction by full txid, unique prefix, or the session id that produced it.

Agent grants

sats agent grant <name> --budget <SATS> [--for <DURATION>] \
  [--max-tx <SATS>] [--max-fee <SATS>]

--for defaults to 24h and accepts human-readable durations such as 30m, 24h, and 7d. Agent names are 1–32 lowercase letters, digits, hyphens, or underscores.

Budget is amount plus fee. --max-tx applies to recipient amount only and --max-fee applies to fee only. Grant creation requires the wallet password.

sats agent list
sats agent revoke claude

Expired grants are removed while listing. Revocation deletes the grant file; an active MCP server observes the deletion on its next send call.

sats agent serve <name> runs the MCP server as that agent. See MCP and agent grants for the tool-level contract.

JSON output

--json is implemented for:

• balance;
• receive;
• send (all three modes);
• status;
• history;
• psbt inspect;
• psbt sign;
• tx broadcast;
• agent grant;
• agent revoke;
• agent list.

JSON field names are compatibility surfaces. Scripts should branch on documented status and reason fields rather than human-readable messages.

init remains an interactive recovery-material flow and deliberately has no JSON mode: emitting the mnemonic on a machine-readable stream invites accidental capture.

Configuration

The default configuration path is the platform-specific XDG config directory for sats. A minimal configuration is:

network = "signet"

Typed providers are configured under [providers.<name>]:

network = "mainnet"

[providers.subfrost]
driver = "subfrost"
network = "mainnet"
url = "https://mainnet.subfrost.io/v4/jsonrpc"
capabilities = ["chain", "guard"]

See Providers and guards for drivers, capability filters, precedence, authentication, and command-line overrides.

Exit and failure behavior

Command failures print a diagnostic to stderr and exit non-zero. Balance, status, and history are the intentionally tolerant chain-read commands: when sync fails without --offline, they report cached state with a stderr warning (synced: false for balance). Planning, signing, provider validation, and broadcast failures remain hard failures.