# CLI

The CLI is designed for shell scripts. Structured command results are written to
stdout. Diagnostics and connection warnings are written to stderr.

Audience: operators, examples, and tests that need reproducible command-line
access to LiteClient, LiteBalancer, contract, TVM, BoC, and schema workflows.
Prerequisites: build with the `cli` feature. Network commands need live network
access; `tvm` commands are offline.

## Global Options

- `--network mainnet|testnet`: public config to download when no config is supplied.
- `--config <path>`: read TON global config JSON from a file.
- `--config-json <json>`: read TON global config JSON from an argument.
- `--output human|json|pretty-json|raw|hex|base64`: select stdout format.
- `--rps <N>`: throttle each selected liteserver to `N` requests per second.
- `--global-rps <N>`: throttle total LiteBalancer request attempts to `N`
  requests per second.
- `--num-servers <N>`: number of allowed liteservers for high-level balancer
  commands after `--exclude-ls` filtering.
- `--exclude-ls <index-or-id>`: exclude liteservers from LiteBalancer paths.
  Repeat the flag or pass comma-separated values. Accepted forms are a decimal
  global-config index (`3`), an explicit index (`index:3`), an explicit
  public-key id (`id:<hex|base64|base64url>`), a bare 64-character hex
  Ed25519 public key, or a bare base64/base64url 32-byte Ed25519 public key.
- `--single --ls-index <N>`: use one reproducible liteserver instead of the
  default high-level balancer.

`--config` and `--config-json` are mutually exclusive. If neither is provided,
the CLI downloads the selected public config when the command needs a network
connection.

## High-Level Network Commands

High-level commands use `LiteBalancer` by default, download the selected public
config when no config is supplied, and print compact human output. Use
`--output json` or `--output pretty-json` for complete structured output.

```bash
tonutils status
tonutils --exclude-ls 0 status
tonutils --exclude-ls index:0 --exclude-ls id:<public-key> status
tonutils account UQBg0E2FCj7kkYWw-2yEcOHs7p1xtnqAoLIYBUG2AJ56eFNP
tonutils --output json account UQBg0E2FCj7kkYWw-2yEcOHs7p1xtnqAoLIYBUG2AJ56eFNP
tonutils call '<addr>' seqno
tonutils call '<addr>' 85143 --arg int:1 --arg null
tonutils call '<addr>' balance --stack-json '[{"type":"int","value":"0"}]'
tonutils call '<addr>' nested --arg 'tuple:[{"type":"int","value":"1"}]'
tonutils call '<addr>' raw --arg unsupported:0a0b
tonutils transactions '<addr>' --count 20
tonutils block latest
tonutils block get '<wc:shard:seqno:root_hash:file_hash>'
tonutils config get
tonutils config get --params 0,17,34
```

`call` accepts typed stack arguments as `null`, `int:<decimal>`,
`cell:<boc-hex>`, `slice:<boc-hex>`, `unsupported:<hex>`,
`tuple:<json-array>`, and `list:<json-array>`, or one inline `--stack-json`
array. Tuple and list typed arguments use the same JSON stack entry objects as
`--stack-json`. `--arg` and `--stack-json` are mutually exclusive. Without
either option, it sends an empty stack.

`account` is best-effort after the strict LiteAPI response parse. If account
state TL-B decoding is incomplete, the command still prints byte lengths, root
hashes for successfully decoded BoCs, and `decode_errors`.

`transactions` needs the account's last transaction hash. Until verified
`ShardAccounts` proof-path extraction lands, the high-level command can report
the current account LT but may return no history with a `decode_error` explaining
that the hash is unavailable. Use `liteclient raw-get-transactions` or
`balancer raw-get-transactions` with an explicit `--lt` and `--hash` when those
values are known.

## Advanced LiteClient Commands

```bash
tonutils --output json liteclient masterchain-info --ls-index 0
tonutils --rps 5 --output json liteclient masterchain-info --ls-index 0
tonutils --output json liteclient version --ls-index 0
tonutils --output json liteclient time --ls-index 0
tonutils --output hex liteclient raw-query --ls-index 0 --hex '<request>'
tonutils --output json liteclient run-get-method --ls-index 0 --address '<addr>' --method seqno
```

Raw query input can be supplied with `--hex`, `--base64`, `--file`, or `--stdin`.

## Advanced Contract Commands

Contract commands use the high-level contract API and the latest masterchain
block reported by the selected liteserver.

```bash
tonutils --output json contract state --ls-index 0 --address '<addr>'
tonutils --output json contract run-get-method --ls-index 0 --address '<addr>' --method seqno
tonutils --output json contract run-get-method --ls-index 0 --address '<addr>' --method-id 85143
tonutils --output json contract run-get-method --ls-index 0 --address '<addr>' --method balance --arg int:0 --arg null
tonutils --output json contract run-get-method --ls-index 0 --address '<addr>' --method balance --stack-json '[{"type":"int","value":"0"}]'
tonutils --output json contract run-abi-get-method --ls-index 0 --address '<addr>' --abi-file contract.abi.json --contract Wallet --method seqno --arg 'owner="<addr>"'
```

JSON state output includes the masterchain block id, shard block id, proof byte
lengths, and raw state bytes as hex and base64. JSON get-method output includes
the execution block ids, exit code, proof byte lengths, raw result BoC, and a
decoded stack when the current stack decoder supports the returned shape.
`contract run-get-method` accepts the same typed `--arg` and `--stack-json`
stack inputs as high-level `call`. JSON stack entries use objects with `type`
set to `null`, `int`, `cell`, `slice`, `tuple`, `list`, or `unsupported`;
integer values are decimal strings and BoC or raw byte payloads are hex strings.
`run-abi-get-method` loads ABI JSON, encodes `--arg name=json` inputs through
the ABI metadata, and renders named decoded outputs. It accepts JSON integer
numbers or decimal/hex integer strings, booleans, strings, hex bytes, address
strings, tuple objects, arrays supported by the stack codec, and cell/slice BoC
hex strings. ABI maps and dictionaries use arrays of `{ "key": ..., "value":
... }` entries and are limited to fixed-width integer keys.

## Wallet Commands

Wallet commands do not store mnemonics or private keys. `wallet generate` is the
only command that prints a mnemonic. Other wallet commands read it from
`--mnemonic-file <path>`, `--mnemonic-file -` for stdin, or
`--mnemonic-env <NAME>`. The default wallet version is V5R1; pass
`--version v4r2` for Wallet V4R2.

```bash
tonutils wallet generate
tonutils wallet address --mnemonic-file seed.txt
tonutils wallet address --version v4r2 --mnemonic-env TON_MNEMONIC
tonutils wallet seqno '<wallet-address>'
tonutils --output hex wallet prepare-transfer --mnemonic-file - --to '<addr>' --amount 100000000 --seqno 0
tonutils wallet send --mnemonic-env TON_MNEMONIC --to '<addr>' --amount 100000000 --deploy
```

Transfer options are `--to <address>`, `--amount <nanotons>`,
`--comment <text>`, `--mode <u8>` defaulting to `3`, `--timeout <seconds>`
defaulting to `60`, optional `--seqno <u32>`, optional `--wallet-id <u32>`,
`--workchain <i8>` defaulting to `0`, and `--deploy` to include `StateInit`.
`prepare-transfer` is offline and requires `--seqno`; `send` fetches `seqno`
unless it is supplied. For `wallet send --deploy`, a missing seqno stack is
treated as seqno `0`; other seqno decoding errors remain errors.

`wallet send` submits one serialized external-in message BoC through
`liteServer.sendMessage` and prints the opaque `SendMsgStatus.status` returned
by the liteserver. That status confirms LiteAPI submission only; it does not
prove transaction inclusion or final execution.

## Advanced Balancer Commands

```bash
tonutils --output json balancer status --num-servers 3
tonutils --rps 5 --global-rps 12 --output json balancer masterchain-info --num-servers 3
tonutils --exclude-ls 0,4,<public-key> --output json balancer status --num-servers 3
```

Balancer commands construct multiple LiteClient peers from the selected config.
They inherit the prototype balancer limits described in
[LiteBalancer](balancer.md).

`--rps` applies to every peer. `--global-rps` applies only to balancer commands
and counts retries and multi-peer message-send attempts as separate requests.
`--num-servers` selects the first N liteservers left after `--exclude-ls`
filtering. Connection warnings keep the original global-config index. Direct
LiteClient commands and high-level `--single --ls-index` commands are explicit
selections and are not blocked by `--exclude-ls`.

## Offline TVM Commands

BoC decode and TL-B inspection commands do not connect to liteservers and do
not require a global config:

```bash
tonutils --output json tvm boc decode --hex '<boc-hex>'
tonutils --output pretty-json tvm boc decode --base64 '<boc-base64>' --tlb account
tonutils --output json tvm boc decode --file state.boc --tlb block
tonutils --output json tvm boc decode --stdin --tlb proof --verify-proof
tonutils --output json tvm schema check
```

BoC input can be supplied with `--hex`, `--base64`, `--file`, or `--stdin`.
Known TL-B decode values are `message`, `message-relaxed`, `transaction`,
`account`, `block`, `config`, `shard-state`, `proof`, and `merkle-update`.
Proof verification flags only check the synthetic primitive invariant that an
exotic Merkle proof/update child hash equals the hash stored in the exotic
cell. They do not establish liteserver trust or validate a block against a
trusted masterchain root.

## Exit Behavior

Successful commands exit with code `0`. Command line parsing errors, network
errors, LiteAPI errors, and invalid input return nonzero exit codes through the
standard Rust error path. Structured command data is written to stdout; human
diagnostics and connection warnings should be treated as stderr.
