wallet-cli account set¶

Set the account's on-chain name or account id.

Synopsis¶

wallet-cli account set (--name <name> | --id <account-id>)
                       [--dry-run | (--sign-only | --build-only) [--expiration <ms>] | --wait [--wait-timeout <ms>]]
                       [--permission-id <n>] [options]

Description¶

Sets the account's on-chain name (a display alias, up to 32 bytes) or its account id (a globally unique identifier, 8–32 bytes). One at a time — --name and --id are mutually exclusive; to set both, run it twice.

⚠️ Each can be set only once and can never be changed — the value is permanent, and there is no confirmation prompt. This is not a mainnet-only rule: the CLI refuses a second write with name_already_set / id_already_set on every network, Nile and Shasta included, so a testnet run is not a rehearsal you can repeat. This is different from rename, which changes the local label and can be redone anytime.

Requires the account. The master password via --password-stdin is needed only when the selected mode signs — --dry-run and --build-only do not unlock the wallet and run without it. Watch-only accounts fail with watch_only_no_signer in a signing mode. The account id's uniqueness is enforced on-chain — a taken id fails with id_taken.

Ledger support differs by field: the TRON app can sign --name, but cannot sign --id (SetAccountIdContract). A Ledger account may still build or dry-run either field; a signing mode with --id fails with ledger_unsupported before device interaction.

Options¶

Option	Description
`--name <name>`	Required (one of). On-chain account name, up to 32 bytes; can be set once, on any network
`--id <account-id>`	Required (one of). Account id, 8–32 bytes, globally unique; can be set once, on any network
`--dry-run`	Build and estimate only; no signature/broadcast, no password. Excludes `--sign-only` / `--build-only`
`--sign-only`	Build and sign, output the signed hex (feed `tx broadcast`). Excludes `--dry-run` / `--build-only`; pairs with `--expiration`
`--build-only`	Build and estimate, output the unsigned hex (feed `tx multisig --create`). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration`
`--expiration <ms>`	Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s)
`--permission-id <n>`	Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0`
`--wait` / `--wait-timeout <ms>`	Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000)
`--password-stdin`	Master password from stdin

Plus the global options.

Examples¶

In the examples, $PW is your master password, fed on stdin via --password-stdin.

Set the on-chain name and wait for confirmation:

echo "$PW" | wallet-cli account set --name "Acme Treasury" --network tron:3448148188 --wait --password-stdin

✅ On-chain name set
  Address  TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw
  Name     Acme Treasury
  TxID     f2b...
  Block    #84,341,590
  Fee      0.3 TRX
  Status   success

echo "$PW" | wallet-cli account set --name "Acme Treasury" --network tron:3448148188 --wait --password-stdin -o json

{"schema":"wallet-cli.result.v1","success":true,"command":"account.set","data":{"kind":"account-set","stage":"confirmed","txId":"f2b...","confirmed":true,"blockNumber":84341590,"feeSun":300000,"failed":false,"field":"name","value":"Acme Treasury","address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw"},"meta":{"durationMs":6420,"warnings":[]},"chain":{"family":"tron","network":"tron:3448148188","chainId":"3448148188"}}

Set the account id instead (--id); the id's uniqueness is enforced on-chain:

echo "$PW" | wallet-cli account set --id acme-treasury-01 --network tron:3448148188 --wait --password-stdin

✅ On-chain id set
  Address  TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw
  ID       acme-treasury-01
  TxID     3d9...
  Block    #84,341,730
  Fee      0.3 TRX
  Status   success

Output¶

data varies by stage:

Stage	Fields
default (submit)	`kind: "account-set"`, `stage: "submitted"`, `txId`, `field` (`name`/`id`), `value`, `address`
`--wait` (confirmed)	the above, but `stage: "confirmed"`, plus `confirmed`, `blockNumber`, `feeSun`, `failed`
`--dry-run`	`kind`, `mode: "dry-run"`, fee estimate, `field`, `value`, `address`; no `txId`

Exit status¶

0 submitted (or built/signed/dry-run in early-exit modes) · 1 execution failure (name_already_set, id_already_set, id_taken, watch_only_no_signer, ledger_unsupported — Ledger signing with --id, auth_failed, rpc_error, timeout) · 2 usage error (invalid_value, invalid_option — malformed or missing name/id).

After a confirmed transaction the command reads the account back to verify the change took effect. That follow-up never turns an already-paid transaction into a command failure: a mismatch or an unreadable read is reported as a meta.warnings entry (account_set_postcheck_mismatch / account_set_postcheck_unavailable) with success still true and exit 0.