| name | wallet-cli |
| description | Operate a TRON wallet from the command line — create/import wallets, query balances and history, send TRX/TRC20/TRC10, check transaction status, stake resources, and sign via software or Ledger. Use for any TRON wallet operation when the wallet-cli binary is available. |
wallet-cli — agent usage
TRON CLI wallet with a machine contract: stable JSON envelopes, deterministic exit codes, secrets via stdin only.
If wallet-cli is not on PATH: npm install -g @tron-walletcli/wallet-cli (requires Node.js 20+). Never install the bare npm name wallet-cli — that is an unrelated third-party package.
Invocation rules (always)
- Always pass
-o json. Parse stdout as a single JSON object, schema wallet-cli.result.v1.
- Branch on exit code first (
0 ok, 1 execution failure, 2 your call was malformed), then on error.code. Never parse error.message.
- Always pass
--network tron:nile for tests; tron:mainnet moves real funds.
- Secrets go through stdin flags (
--password-stdin), never argv/env. Only one *-stdin flag per run. Mnemonic/private-key import and change-password are interactive-only (hidden TTY input) — hand those to the human; an agent cannot drive them.
- All on-chain amounts in JSON are decimal strings — do not treat as numbers.
--timeout <ms> bounds every RPC/device call (default 60000).
Command map
create --label <l> new HD wallet (BIP39)
import mnemonic|private-key|ledger|watch bring in existing accounts
list / use <acct> / current enumerate & select active account
derive / rename / backup / delete account lifecycle (backup: secret, file mode 0600)
address generate keypair made locally; NOT added to the wallet
account balance|info|history|portfolio on-chain state (history needs TronGrid)
account activate --address <addr> activate a new account (payer = active account)
account set --name <n> | --id <n> one-time on-chain name/ID — effectively immutable
tx send --to <addr|contact> --amount <n> TRX; add --token SYM | --contract Txx | --asset-id N for tokens
[--dry-run|--sign-only|--build-only] estimate only / sign / build unsigned, no broadcast
tx sign --transaction <json> sign JSON built elsewhere
tx sign --file <hex> [--check] [--out] append a signature to a multi-sig artifact (--check verifies online)
tx approvals --file <hex> who signed, weight so far, missing weight, expiry
tx multisig [--create|--sign <id>|--watch] collect signatures via the TronLink service
tx broadcast --tx-stdin|--hex|--file broadcast a presigned tx; --dry-run validates only
tx status --txid <id> state: confirmed|failed|pending|not_found
tx info --txid <id> full detail + receipt
permission show owner/witness/active groups, thresholds, decoded ops
permission update --file <json> replace the WHOLE permission structure (lockout risk)
gasfree info|transfer|trace send tokens with no TRX; fee paid in the token
stake freeze|unfreeze|withdraw|cancel-unfreeze|delegate|undelegate resource staking
token / contract / message / block address book, smart contracts, signing, blocks
contact add|list|remove recipient names usable as --to <name>
encoding convert <value> base58 / 41-hex / 0x-EVM / hex / base64 conversions
config / networks local config, known networks
Multi-sig: build unsigned (--build-only) → each signer tx sign --file … --out → check with
tx approvals → tx broadcast once thresholdReached is true. tx broadcast refuses a
transaction below its threshold, so branch on data.thresholdReached, never on exit code alone.
Details for any command: wallet-cli <command> --help.
Transaction safety (mandatory)
tx send returns at submission (data.stage: "submitted", data.txId) — that is NOT confirmation.- Either add
--wait (blocks until confirmed/failed, cap --wait-timeout), or poll tx status until data.state is confirmed; abort on failed; pending/not_found mean keep polling within your own deadline.
- Before any mainnet send: confirm with the user; consider
--dry-run first (builds + estimates, no signature, no broadcast).
Dangerous commands — require explicit user confirmation
tx send / tx broadcast / contract send|deploy / gasfree transfer on tron:mainnet (moves funds) · delete (removes accounts; HD delete cascades from the seed root) · backup (writes secret material to disk) · address generate --print-secret (writes a private key to stdout).
permission update is the most dangerous command in the CLI — it replaces the account's entire permission structure, and a structure whose owner group excludes your keys locks the account permanently, with no recovery. Never run it without --dry-run first and explicit user confirmation of the rendered structure. Heed owner_lockout / owner_lockout_partial warnings.
account activate and account set are one-shot: an account activates once, and the on-chain name and ID can each be set once.
Error handling
| exit | error.code | action |
|---|
| 2 | usage_error, invalid_value | fix flags; re-read --help |
| 1 | timeout | retry with higher --timeout; check network/proxy |
| 1 | rpc_error | node rejected: inspect message for context, verify txid/address/funds |
| 1 | internal_error | do not retry blindly; report |
Full contract: docs/machine-interface.md in the wallet-cli repository.
