Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

The circuit wallet namespace manages an encrypted local keystore that holds the keys (or hosted-wallet links) circuit dev run uses to sign in local mode. The keystore lives at ~/.config/circuit/keystore.enc by default, encrypted with Argon2id-derived AES-256-GCM, and is unlocked with a password prompt every time you run a wallet command. Override the location with --keystore <path>.
The keystore is for circuit dev run (local mode). Hosted runs (circuit dev run --hosted) use Circuit’s KMS infrastructure and don’t need a local key.

​
List Wallets

circuit wallet list
Prints one TSV row per wallet (ADDRESS\tTYPE\tKIND\tNAME) so the output is pipe-friendly. The NAME column shows the friendly hosted-wallet name captured at link time for kind=remote entries (display only — lookups still go through the address); - for local entries. Use --format json for a structured response. If no keystore exists yet, this exits 0 with an empty list and a hint to circuit wallet add.

​
Add Wallet

circuit wallet add
Interactive — prompts for a source:
  1. Hosted (recommended): connects to your Circuit account, lists your hosted wallets, and stores a link to the one you pick. Per-agent dev permits are minted lazily on first circuit dev run.
  2. Import: prompts for a private key in a masked password field (never echoes to the terminal, scrollback, or script(1) capture).
  3. Generate: creates a fresh EVM secp256k1 or Solana ed25519 keypair from OS entropy.
The very first circuit wallet add against a missing keystore prompts for a new password (twice, for confirmation). Subsequent adds prompt for the existing password. For locally-stored keys, circuit wallet add prints a one-line tip pointing at circuit wallet export for backup — local keys are not recoverable elsewhere.

​
Delete Wallet

circuit wallet delete <address>
Removes a wallet from the keystore. Requires confirmation. For hosted wallets, also revokes any still-live dev permits server-side so the credential can’t be re-used after delete. For local wallets this permanently loses the key bytes — they aren’t stored anywhere else.

​
Export Wallet

circuit wallet export <address>
Audited escape hatch — decrypts a local key and prints it to stderr (so a shell > redirect doesn’t accidentally capture it; use 2> if you genuinely want to file it). Requires the user to type yes I understand before printing. Refused for hosted-wallet links — use the web app’s wallet-export flow if you need the underlying key behind a hosted wallet.

​
Keystore file location

circuit wallet honors two paths to override the default ~/.config/circuit/keystore.enc:
MechanismScopeExample
--keystore <path> flagper-commandcircuit wallet list --keystore /tmp/k.enc
CIRCUIT_CONFIG_PATH env varoverrides the whole config dirCIRCUIT_CONFIG_PATH=/etc/circuit circuit wallet list
The keystore file is always written with 0600 permissions (owner read/write only); circuit wallet refuses to read a keystore that has been chmod’d looser than that.