Wallet CLI

TRON Wallet CLI

Use the TypeScript, one-shot wallet-cli as the execution engine. Keep deterministic wallet, signing, validation, and chain logic in the CLI; use this skill to select commands, enforce authorization boundaries, and interpret results.

This skill does not drive the repository's Java REPL and does not replace protocol-specific skills such as SunSwap. Use a DEX skill for swaps or liquidity workflows and this skill for the wallet, signing, resource, governance, and general TRON operations beneath them. If the user requests the Java REPL, do not execute it or offer to switch to it; state that this skill supports only the TypeScript one-shot CLI and, when applicable, offer to express the intended operation through that interface.

Verify the dependency

Check once before the first wallet operation:

npm list --global --depth=0 --json @tron-walletcli/wallet-cli

Read dependencies["@tron-walletcli/wallet-cli"].version from the JSON. The required version is exactly 4.14.0. In this version, --version, --help, --json-schema, and a bare wallet-cli skip wallet-data access and the startup migration gate. Operational commands can still upgrade persisted wallet data before executing.

• If the command is missing, explain that the exact package @tron-walletcli/wallet-cli@4.14.0 must be installed and obtain user approval before running npm install -g @tron-walletcli/wallet-cli@4.14.0.
• If another version is installed, report the mismatch and obtain approval before upgrading or downgrading it. Do not assume compatibility.
• Never install or change a global package without approval.

Mandatory invocation contract

1. Use -o json for every operational command. Parse stdout as exactly one wallet-cli.result.v1 object.
2. Supply an explicit canonical network for chain operations: mainnet tron:728126428, Nile tron:3448148188, or Shasta tron:2494104990. Never silently choose mainnet. Use tron:3448148188 when the user explicitly asks for a test but does not distinguish between testnets. The old tron:mainnet, tron:nile, and tron:shasta values are permanent input aliases, but never expect an alias in chain.network, network listings, or configuration keys.
3. Branch on the process exit code first: 0 success, 1 execution failure, 2 malformed call. Then branch on stable fields such as error.code, data.stage, or data.state. Never parse error.message text.
4. Treat bigint values and command-defined on-chain amount fields as decimal strings. Preserve every field according to the leaf schema; other counters and configuration values may be JSON numbers. Never use floating point for string amounts.
5. Set --timeout <ms> when the surrounding task has a tighter deadline than the CLI's 60-second default.
6. Never infer that exit code 0 means a transaction confirmed. A submitted or reverted transaction can still have a successful command envelope.

Read references/machine-interface.md before implementing result parsing, polling, pagination, retry logic, or non-interactive secret input.

Handle the startup migration gate

Operational commands check persisted wallet data before running the requested command. Discovery invocations (--help, --version, --json-schema, and bare wallet-cli) skip this check. If the result envelope has command: "migration", the requested command did not run. Inspect data.originalCommandExecuted, which must be false for a migration result.

• If data.upgraded is true, report that local wallet data was upgraded, then reapply the authorization and confirmation rules before running the original command once. A mainnet or high-risk confirmation given before migration must be obtained again. Do not interpret migration data as command data.
• If data.cancelled is true, stop and return control to the user. Do not retry or bypass the cancellation.
• If exit 2 returns error.code: "migration_required", stop. The user must complete the upgrade interactively or provide the master password through an already approved --password-stdin source. Never ask for the password in chat.
• Never loop on a migration result. After one successful upgrade, a repeated migration response is an error to report rather than a reason to keep retrying.

Discover commands instead of guessing

Prefer the CLI's generated schema over recalled flags:

wallet-cli --json-schema -o json
wallet-cli tx send --json-schema -o json
wallet-cli permission update --json-schema -o json

Use wallet-cli <command> --help only when human-oriented semantics are needed. Do not invent a flag, option combination, output field, or command that is absent from the 4.14.0 schema.

Read references/commands.md when choosing a command family or composing a multi-step wallet workflow.

Secret handling

• Reject any request to put a wallet password in --password or another argv option. For agent-driven execution, explain that wallet-cli passwords may be supplied only through --password-stdin connected directly to an approved, non-logging secret source.
• Never ask the user to paste a password, mnemonic, private key, or service credential into chat.
• Never place secrets in argv, environment variables, logs, command substitutions, or generated documentation.
• Use only a CLI-supported *-stdin flag connected to an approved, non-logging secret source. Only one *-stdin consumer may be used in a single invocation.
• Do not read, summarize, or transmit keystores, backup files, configuration credentials, or other wallet secret material.