Wallet Modes
The Doma CLI signs writes in one of two modes. The mode you pick determines what holds the signing authority, what scope it has, and how revocable it is.
The two modes
agent (Privy delegated)
Doma launchpad → Privy delegated signer
doma auth login (browser consent)
USD-capped, scoped to Doma chains
private-key (default)
Local raw key in ~/.doma/config.json or env
export DOMA_PRIVATE_KEY=0x…
Unbounded, limited only by wallet balance
Both modes are first-class. The transactional flow is byte-identical; only the authentication setup and revocation story differ.
Which mode should I pick?
Find your situation in the table:
CI, cron, or any non-interactive run
private-key
Need a USD spend cap or infra-enforced chain allowlist
agent
Personal dev box, want hands-off browser consent
agent
Personal dev box, prefer a dedicated test wallet
private-key
Production server with a secrets manager
private-key
Already use Doma in your browser, want one-command auth
agent
When in doubt: start with private-key on testnet, switch to agent for any wallet that holds value worth protecting.
Setting up agent mode
Requires Doma CLI ≥ 0.5.0. The CLI runtime-detects support via doma auth --help (older versions return non-zero).
Agent mode is supported on both Doma Mainnet (chain 97477) and Doma Testnet (chain 97476). The active network is whichever your config / --testnet flag selects; doma auth login mints a session for that network. To use both networks, run doma auth login once per network.
The CLI prints a localhost URL. Open it in your browser. You'll see a Privy-hosted consent screen. Review the wallet being authorized, the allowed chains and RPC methods, and the spend ceiling (default $200 USD), then confirm. Once approved, the CLI prints Authorized. and writes a session JWT to ~/.doma/credentials.json (mode 0600).
Persist the choice so future commands use agent mode by default:
The browser consent screen is the actual authorization moment. The CLI does not prompt again. If you change your mind, click Cancel in the browser and the session is never minted.
Setting up private-key mode
Set the key as an environment variable in your shell:
Or persist it via the CLI (macOS uses Keychain by default, see Install & Configure):
Then mark the mode explicitly (this is the default, but explicit beats implicit):
Use a dedicated wallet for the CLI. The key on disk is fully empowered: anything that can read the file can drain the wallet. Don't reuse a personal hardware-wallet-derived key here.
Switching modes
The CLI uses whichever mode is active at command time. Read commands (token, quote, balance) work in either mode without auth.
Revoking an agent session
This calls Privy to detach the agent's authorization key from your wallet, deletes ~/.doma/credentials.json, and clears walletMode. Future writes require a fresh doma auth login.
You can also revoke from the launchpad's "Authorized agents" panel at any time. Useful if your machine is lost.
Checking session status
Output:
Trade-offs at a glance
agent
private-key
Key on disk
No (Privy HSM)
Yes
Spend cap
Hard-enforced ($200 default)
None
Chain allowlist
Doma chains only
All chains
Revoke from another machine
Yes (launchpad UI)
Need to rotate the key
Works in CI / non-interactive
No (needs browser consent)
Yes
Available since
CLI 0.5.0
All versions
What's next
Commands: full reference of what the CLI can do.
Agentic Wallet: deeper architectural look at the Privy delegated signer.
Last updated