# 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: a second write is refused 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`](../rename.md), 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` never unlock the wallet. 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 not `--id` (`SetAccountIdContract`). A Ledger account can still build or dry-run either field; a signing mode with `--id` fails with `ledger_unsupported` before the device is touched.

## 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`](../tx/broadcast.md)). Excludes `--dry-run` / `--build-only`; pairs with `--expiration` |
| `--build-only` | Build and estimate, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md)). 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](../index.md#global-options-every-command).

## Examples

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

Set the on-chain name and wait for confirmation:

```bash
echo "$PW" | wallet-cli account set --name "Acme Treasury" --network nile --wait --password-stdin
```

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

```bash
echo "$PW" | wallet-cli account set --name "Acme Treasury" --network nile --wait --password-stdin -o json
```

```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":"TP2Zs9qKScTMs8jDYV3SAHQ5pqgKY1NQ5V"},"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:

```bash
echo "$PW" | wallet-cli account set --id acme-treasury-01 --network nile --wait --password-stdin
```

```console
✅ On-chain id set
  Address  TP2Zs9qKScTMs8jDYV3SAHQ5pqgKY1NQ5V
  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`.

## See also

[`account activate`](activate.md) · [`rename`](../rename.md) · [`account info`](info.md)