# CLI reference

The `tonado` CLI is the canonical user-facing interface to the protocol. It wraps the SDK and provides commands for note management, deposits, withdrawals, and pool inspection.

## Installation

Until the CLI is published to npm, link the dev build globally:

```bash
pnpm install
pnpm --filter @tonado/cli run build
pnpm --filter @tonado/cli run link:dev
```

After this, `tonado` is available globally on your machine.

## Configuration

The CLI reads from environment variables (or a `.env` file in the working directory):

```ini
TON_NETWORK=testnet
TONCENTER_ENDPOINT=https://testnet.toncenter.com/api/v2/jsonRPC
TONCENTER_API_KEY=<your key>
TONADO_USER_MNEMONIC="word1 word2 ..."   # optional default mnemonic
TONADO_USER_WALLET_VERSION=v4R2
TONADO_RELAYER_URL=http://localhost:8090
```

Flags override env vars (`--network`, `--mnemonic`, `--relayer`, etc.).

## Commands

### `tonado note generate <asset> <amount>`

Generate a random deposit note locally. **Does not deposit on-chain.** Useful for testing or staging.

```bash
tonado note generate ton 1 --network testnet
```

### `tonado note parse <note>`

Decode a note string into its component fields (asset, amount, network, derived commitment, derived nullifier hash). Purely local, no network calls.

```bash
tonado note parse "tonado-ton-1-testnet-0xabcd..."
```

### `tonado note check <note>`

Query the pool's on-chain state for the note's nullifier hash. Tells you whether the note has been spent.

```bash
tonado note check "tonado-ton-1-testnet-0xabcd..." --network testnet
```

### `tonado deposit native <amount>`

Deposit native TON. Generates a fresh note, signs the deposit transaction from the supplied mnemonic, sends it, then prints the note.

```bash
tonado deposit native 1 \
  --mnemonic "..." \
  --network testnet
```

**Save the note immediately.** Without it, the deposit is permanently unrecoverable.

### `tonado deposit jetton <jetton-master-address> <amount>`

Deposit a TEP-74 Jetton. Routes the deposit via the user's jetton wallet → the pool's jetton wallet → a `transfer_notification` to the pool. The pool's counterfeit-jetton check (`senderAddress == config.poolJettonWallet`) rejects any sender that isn't the bound wallet.

```bash
tonado deposit jetton "EQAjetton-master-addr" 100 \
  --mnemonic "..." \
  --network mainnet
```

The pool entry for `jetton:<master>-<amount>` must already exist in [`packages/core/src/deployments.ts`](https://github.com/tonadocash/monorepo/blob/main/packages/core/src/deployments.ts).

### `tonado withdraw self <note> <recipient>`

Withdraw using the user's own wallet to pay gas. **Defeats privacy**: the gas-paying wallet is on-chain and linked to the withdrawal. Use only for testing.

```bash
tonado withdraw self \
  "tonado-ton-1-testnet-0xabcd..." \
  "EQRecipient..." \
  --mnemonic "..."
```

### `tonado withdraw relay <note> <recipient>`

Withdraw via a relayer service. The relayer pays gas and takes a small fee. **This is the normal path.** The note never leaves your machine; the relayer only receives the broadcast-ready proof + payload.

```bash
tonado withdraw relay \
  "tonado-ton-1-testnet-0xabcd..." \
  "EQRecipient..." \
  --relayer http://localhost:8090
```

### `tonado pools list`

Print all configured pools for the active network.

```bash
tonado pools list --network testnet
```

### `tonado pools stats <asset> <amount>`

Query the pool's on-chain state: address, deposit count, current Merkle root, anonymity-set size.

```bash
tonado pools stats ton 1 --network testnet
```

### `tonado relayer status [--url URL]`

Health-check a relayer service. Reports the relayer's address, fee policy, network, and sync state.

```bash
tonado relayer status --url http://localhost:8090
```

## Behaviors worth knowing

* The CLI **never writes notes to disk**, **never logs them**, and **never sends them over the network**. Notes are produced on stdout exactly once.
* The CLI **caches downloaded circuit artifacts** under `packages/core/artifacts/` between invocations. If you regenerate the circuit, delete the cache.
* Long-running operations (proof generation, ptau download) print progress to stderr. stdout stays clean so output can be piped.
* `--help` is supported at every level (`tonado --help`, `tonado deposit --help`, etc.).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tonadocash.com/for-developers/cli-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.