Callers
CLI reference
Every toon-client setting and command, and where each value comes from.
The CLI ships in @toon-protocol/client. Its executable is toon-client, so npx toon-client runs it without a global install; npx toon resolves to an unrelated package and fails. This is the payer's CLI. The program that runs an agent node is called toon and lives in toon_cli; the two are different programs.
npx toon-client help npx toon-client help send
Settings, and where each comes from
Every setting resolves the same way: flag, then environment variable, then default. A default that is a guess rather than a fact is announced on stderr, because falling back to a connector nobody named should not be silent.
| Setting | Flag | Environment | Default |
|---|---|---|---|
| Connector | --connector URL | TOON_CONNECTOR | The devnet store node, with a warning |
| Keys | — | TOON_MNEMONIC | The keystore, below |
| Keystore | --keystore PATH | TOON_KEYSTORE | ~/.toon/keystore.json |
| Keystore password | --password-file PATH | TOON_KEYSTORE_PASSWORD | A hidden prompt, when stdin is a TTY |
| Chain | --chain evm|solana | TOON_CHAIN | The first chain the node is paid on that you hold a key for |
| RPC | --rpc URL | TOON_RPC_URL | The package's preset for the chosen chain |
| Channel store | --store PATH | TOON_CHANNEL_STORE | ~/.toon/channels.json |
| Carriage | --transport auto|http|btp | — | auto |
| SOCKS5h proxy | --socks URL | TOON_SOCKS | A managed anon daemon, for a .anyone connector |
| x402 facilitator | --facilitator URL | TOON_FACILITATOR | The one the connector names, else the devnet's own on Base Sepolia |
| Who pays deposit gas | --deposit-gas auto|facilitator|self | TOON_DEPOSIT_GAS | auto: the facilitator, else your own ETH |
| How the token moves | --deposit-method eip3009|permit2 | TOON_DEPOSIT_METHOD | What the connector names, else eip3009 |
Keys resolve in that order for a reason: TOON_MNEMONIC first, then the keystore, then a message telling you to run toon-client init. There is no --mnemonic flag and there will not be one. A flag value is written to shell history and is readable in ps by every other user on the machine.
Global flags
| Flag | Effect |
|---|---|
--json | Print exactly one JSON document on stdout and nothing else. |
--quiet | Suppress progress and warnings on stderr. |
-h, --help | Show help for the command. |
--version | Print the client version. |
Commands
| Command | Does | Needs |
|---|---|---|
toon-client init [--import] [--legacy-derivation] | Create or import a keystore. Prints the phrase once. --import reads an existing phrase from stdin, never from an argument. | nothing |
toon-client identity [--all-derivations] | Show the addresses this keystore holds. | keys |
toon-client describe [URL] | Read a connector's self-description: addresses, endpoints, the key payloads are sealed to, which chains and tokens it is paid in, and what each route costs. Refuses a node with no settlement block ("publishes no settlement chains at all"). | no funds; 5.0.0 still opens the keystore, so pass --password-file in a script |
toon-client price <destination> [URL] | What one route costs. A connector that serves no matching route says so: an answer, not a failure. | as above |
toon-client probe <destination> | Learn a path's cost beyond this connector without buying the work. | a channel you have already paid on |
toon-client faucet | Draw devnet USDC from the faucet. | keys |
toon-client balances | Token and native balances on the chosen chain. | keys |
toon-client channel open --deposit N | Open a channel toward the connector, with N base units. Idempotent. | keys, funds |
toon-client channel deposit N | Top up by an increment. | a channel |
toon-client channel status | Your side of the channel: deposit, cumulative, config. | a channel |
toon-client send [destination] --body … | Buy one request. With no destination, the route the connector terminates. Exits 3 on a refusal. | a channel, unless the route is free |
toon-client claim-state | The connector's watermark for your channel, as an owner-authenticated read. | a channel |
The full CLI reference on GitHub covers every command, including leaving a channel, the exit codes, and the exact shape of each --json document.
Written from toon-client/docs/cli.md.