CLI commands
The lookup page. Every canonicalwallet command, grouped by what you're trying to do, with its flags. Required flags are marked •; everything else is optional.
The lookup page. Every canonicalwallet command, grouped by what you're trying to do, with its flags. Required flags are marked •; everything else is optional.
A few things apply everywhere:
- Add --json to any command for machine-readable output.
- Every command proves who you are with --token-file <path> (or --token-stdin). Throughout, wallet is shorthand for canonicalwallet --token-file ~/.canonical/operator.token.
- Any mutating command takes --idempotency-key <key> — pass it in scripts so a retry after a hiccup runs once, not twice.
- If a direct command returns governance_required, your rules require approval for it — use the matching proposal ... version instead.
- Commands that create a proposal also accept quorum flags: --required-principal-id <id> (repeatable), --required-principal-kind <kind> (repeatable), --required-principal-group <json>, plus --expires-at and --execution-deadline (both RFC3339). These are omitted from the tables below to avoid repeating them on every row.
---
Wallet & session#
wallet create
Create a new encrypted wallet.
- • --password <PASSWORD> — wallet password.
- • --account-label <LABEL> — label for the first account.
- --word-count <COUNT> — mnemonic length; default and only supported value is 24.
wallet import-mnemonic
Import an existing recovery phrase into a new wallet.
- • --password <PASSWORD>, • --account-label <LABEL>, • --mnemonic-phrase <MNEMONIC>.
wallet unlock
Decrypt the vault into memory so the wallet can sign.
- • --password <PASSWORD>.
- --idle-timeout-seconds <SECONDS> — auto-lock after inactivity; default 900 (15 min).
wallet lock
Wipe the decrypted keys from memory. No flags beyond the common ones.
wallet derive-account
Add another address from the same phrase.
- • --password <PASSWORD>, • --account-label <LABEL>, • --account-index <INDEX>.
wallet reveal-backup
Show the recovery phrase — only works before backup verification.
- • --password <PASSWORD>.
wallet verify-backup
Confirm you saved the phrase; unblocks signing.
- • --password <PASSWORD>.
- • --check <POSITION:WORD> (repeatable) — the word-position checks it asks for.
---
Reads (no flags unless noted)#
| Command | Shows | Flags |
|---|---|---|
| status | Lock state, active chain, wallet presence, backup state. | — |
| me | Your principal and its capabilities. | — |
| accounts | Your addresses. | — |
| manifest | The full generated command/tool surface. | — |
| chains list | Configured networks and which is active. | — |
| client list | Registered clients. | — |
| policy list | Approval rules and their requirements. | — |
| policy inspect <POLICY_ID> | One rule in detail. | positional id |
| activity list | Human-readable timeline. | --limit |
| audit list | Append-only hash-chained log. | --limit |
| events list | Machine event stream. | --after-sequence, --limit, --proposal-id, --actor-principal-id, --kind-prefix, --proposals-only |
| inbox me | Proposals waiting for your action. | --assigned-only, --ready-only, --state, --limit |
| permissions list | Per-origin allowances. | --origin, --limit |
| contacts list | Address book. | --limit |
| assets list | Watched assets. | --chain-id, --limit |
---
Proposals — create#
All of these create a durable proposal (default rule: two approvals, one human) and accept the quorum flags noted at the top.
proposal tx
A direct transaction.
- • --chain-id, • --from, • --to, • --value-wei.
- --data <HEX> — optional calldata. --rationale <TEXT>.
proposal replace
Replace an already-executed transaction.
- • --proposal-id <ID> — the executed proposal to replace.
- • --strategy <STRATEGY> — speed_up or cancel. --rationale.
proposal safe
A Gnosis Safe transaction.
- • --chain-id, --safe-address, --owner-account (repeatable), --to, --value-wei, --data, --operation, --nonce, --threshold.
proposal sign-personal
Sign a message (EIP-191) after approval.
- • --account <ADDRESS>, • --payload-hex <HEX>. --rationale.
proposal sign-typed-data
Sign typed data (EIP-712) after approval.
- • --account <ADDRESS>, • --payload-json <JSON>. --rationale.
proposal add-chain / proposal switch-chain
Governed network changes. add-chain mirrors chains add's flags; switch-chain takes • --chain-id. Both add --rationale.
proposal grant-permission / proposal revoke-permission
Governed per-origin permission changes; mirror the permissions flags below plus --rationale.
proposal register-client / proposal revoke-client
Governed client-registry changes; mirror the client flags below plus --rationale.
proposal change-policy
Change an approval rule (itself needs two-human approval).
- • --template-id <POLICY_ID>, • --required-total <COUNT>.
- --human-required (flag), --approval-required-principal-id / -kind / -group (define the new rule), --rationale.
---
Proposals — review, decide, execute#
Every command here takes the proposal id as a positional argument.
| Command | What it does | Notable flags |
|---|---|---|
| proposal list | Browse proposals. | --state, --limit |
| proposal get <ID> | Read one proposal. | --review, --summary |
| proposal review <ID> | The frozen semantic review. | --summary |
| proposal resimulate <ID> | Fresh review, no state change. | --timeout-ms |
| proposal compare-review <ID> | Drift check vs the approved review. | --summary, --diff, --fail-on-drift, --timeout-ms |
| proposal decision <ID> | What you can do right now. | --summary, --timeout-ms |
| proposal why-not-executable <ID> | What still blocks execution. | --summary |
| proposal approve <ID> | Approve, against the frozen review. | --rationale |
| proposal reject <ID> <REASON> | Reject (reason required). | — |
| proposal cancel <ID> <REASON> | Cancel (reason required). | — |
| proposal execute <ID> | Final checks, sign, broadcast. | — |
--fail-on-drift on compare-review is handy in scripts: it exits non-zero when drift is detected, so you can gate execution on it.
---
Proposals — team workflow (coordination only)#
Positional proposal id; none of these approve anything.
| Command | What it does | Flags |
|---|---|---|
| proposal claim <ID> | Signal you're working it. | — |
| proposal release-claim <ID> | Drop your claim. | — |
| proposal handoff <ID> | Pass to another principal. | • --to <PRINCIPAL_ID>, --reason |
| proposal mark-reviewed <ID> | Record that you reviewed it. | --notes |
| proposal request-changes <ID> | Ask for changes. | • --reason <TEXT> |
| proposal workflow <ID> | Read the workflow record. | --summary, --timeout-ms |
---
Chains#
chains add
Register a network and probe its RPC.
- • --chain-id, --name, --rpc-url (repeatable), --native-currency-name, --native-currency-symbol.
- --explorer-url (repeatable), --native-currency-decimals (default 18).
chains switch
Activate a known network.
- • --chain-id.
---
Clients (access tokens)#
client register
Add a client. Needs manage_clients (your operator token has it).
- • --label, • --principal-kind <KIND>, • --capability (repeatable).
- One of --client-token, --client-token-file <PATH> (recommended), or --client-token-stdin. --expires-at for a time-bound token.
client rotate-token <REGISTRATION_ID>
New secret, same identity.
- One of --client-token / --client-token-file / --client-token-stdin; optional --expires-at.
client revoke <REGISTRATION_ID>
Cut off a client.
---
Permissions (per-origin)#
permissions grant
- • --origin, • --allowed-method (repeatable).
- --account-id (repeatable), --rationale.
permissions revoke
- • --origin. --rationale.
---
Address book & watched assets#
contacts upsert
- • --label, • --address. --chain-id, --note.
contacts remove
- • --contact-id.
assets watch
- • --asset-type, --chain-id, --address, --symbol, --decimals. --image-url.
---
Direct signing & decoding#
sign personal / sign typed-data
Sign immediately (still policy-gated).
- sign personal: • --account, • --payload-hex.
- sign typed-data: • --account, • --payload-json.
calldata decode
Explain any calldata without creating a proposal.
- • --to <ADDRESS>, • --data <HEX>. --chain-id, --value-wei, --timeout-ms.