CLI Quick Reference

Commands

Command	Description
`circuit login`	Authenticate via browser (details)
`circuit logout`	Clear stored credentials (details)
`circuit whoami`	Show current user (details)
`circuit new`	Create new agent project (details)
`circuit dev run`	Execute agent locally; `--hosted backend` to use the hosted execution (details)
`circuit dev unwind`	Unwind agent locally; `--hosted backend` to use the hosted execution (details)
`circuit check`	Validate project offline (details)
`circuit publish`	Publish to Circuit infrastructure (details)
`circuit wallet list`	List wallets in the local vault (details)
`circuit wallet add`	Add a local wallet (imported or generated) (details)
`circuit wallet delete <address>`	Remove a wallet from the vault (details)
`circuit wallet export <address>`	Decrypt and print a local key (details)

Global Flags

Available on all commands:

Flag	Short	Description
`--path <path>`	`-p`	Agent project directory (default: current directory)
`--format <mode>`	`-f`	Output format: `text` (default), `json`, or `stream-json`
`--help`	`-h`	Show command help

`circuit new` Flags

Flag	Short	Values	Description
`--language`	`-l`	`typescript`, `python`	Skip language prompt
`--name`	`-n`	any string	Skip name prompt
`--template`	`-t`	`basic`, `yield`, `polymarket`, `hyperliquid`	Skip template prompt

`circuit dev run` Flags

Flag	Short	Description
`--hosted <level>`		Host up through `signing` (KMS signing), `backend` (+ hosted execution: sessions, policy, funding), or `runtime` (+ agent runs in the hosted Lambda). Omit for fully local; each level includes the ones below it.
`--wallet <address>`	`-w`	Local keystore wallet address, or hosted wallet address with `--hosted backend`
`--mode <mode>`	`-m`	`auto` or `manual` (default: first in `allowedExecutionModes`)
`--amount <amount>`	`-a`	Token amount in smallest unit
`--env KEY=VALUE`	`-e`	Set/override env var (repeatable)
`--setting KEY=VALUE`	`-s`	Override a `circuit.toml` setting (repeatable). Required for settings marked `required = true`.
`--local-sdk-dependencies`	`-l`	Skip automatic dependency installation
`--port <port>`		Fixed port for the agent server (skips automatic port selection)

`circuit dev unwind` Flags

Flag	Short	Description
`--hosted <level>`		Host up through `signing` (KMS signing), `backend` (+ hosted execution), or `runtime` (+ agent runs in the hosted Lambda). Omit for fully local; each level includes the ones below it.
`--wallet <address>`	`-w`	Local keystore wallet address, or hosted wallet address with `--hosted backend`
`--env KEY=VALUE`	`-e`	Set/override env var (repeatable)
`--setting KEY=VALUE`	`-s`	Override a `circuit.toml` setting (repeatable). Required for settings marked `required = true`.
`--local-sdk-dependencies`	`-l`	Skip automatic dependency installation
`--port <port>`		Fixed port for the agent server (skips automatic port selection)

dev run and dev unwind print one transaction diagnostic per attempt, for example tx confirmed [ethereum:8453]: https://basescan.org/tx/0x... or tx failed [ethereum:8453]: <error>. In stream-json mode these are output envelopes; in json mode they are included in txAttempts.

`circuit check` Flags

Flag	Short	Description
`--env KEY=VALUE`	`-e`	Set/override env var for validation (repeatable)

`circuit publish` Flags

Flag	Short	Description
`--env KEY=VALUE`	`-e`	Set/override env var (repeatable)

`circuit whoami` Flags

Flag	Short	Description
`--reveal auth`		Print the raw API auth token (the passkey-signed permit) for CI/CD

`circuit check` Output

Validates offline (no auth required):

Config structure (valid circuit.toml)
Entry point exists (index.ts or main.py)
Default export is an Agent instance (TypeScript) or top-level agent variable (Python)
SDK version pinning
Environment variable cross-referencing
TypeScript typecheck (tsc -p .; catches hallucinated SDK methods, unknown imports, type errors). Requires installed dependencies — run bun install first.
Python syntax check (py_compile on main.py; catches parse errors). Requires .venv/bin/python3 or system python3.

File Exclusion (Publish)

Automatically excluded from uploads:

Category	Patterns
Version control	`.git/`, `.svn/`
Dependencies	`node_modules/`, `dist/`, `venv/`, `__pycache__/`
Secrets	`.key`, `.pem`
IDE	`.vscode/`, `.idea/`, `*.swp`
Build artifacts	`coverage/`, `.pytest_cache/`, `.cache/**`
Unsupported lock files	`package-lock.json`, `bun.lockb`, `yarn.lock`, `pnpm-lock.yaml`
Other	`Dockerfile`, `docker-compose.yml`, `.md`, `.sh`, `*.log`, `.DS_Store`

Additional patterns via filesToExclude in circuit.toml. TypeScript publishes require an up-to-date bun.lock.

Environment Variables

Source: .env in project root + --env CLI flags (flags take precedence)
Supported commands: dev run, dev unwind, validate, publish
Local execution (dev run, dev unwind): Env vars are injected into the spawned agent process
Publish: Encrypted at rest, decrypted at deploy time
Access: process.env.KEY (TypeScript) / os.getenv("KEY") (Python)
Limit: 4 KB total (including system vars)
Rotation: Republish to update

Auth Storage

Credentials stored in ~/.config/circuit/auth.toml after circuit login: a passkey-signed permit (circuit_permit_<payload>.<proof>) used as the API auth token. There is no separate wallet-execution token — the api resolves wallet-signing material server-side from the permit’s wallet.sign capability. One file with a [production], [staging], or [local] section per environment — set CIRCUIT_ENV to switch which section the CLI reads. (Same single-file pattern as ~/.aws/credentials or gh hosts.yml.)

CI / headless auth

Set CIRCUIT_TOKEN to an API auth token (a passkey-signed permit) to skip circuit login entirely. The CLI reads this env var before looking for a config file, matching the convention used by GH_TOKEN, NPM_TOKEN, etc. Hosted-runtime commands resolve wallet-signing material from the permit, so no separate wallet-execution token is needed. Capture the token from a logged-in machine:

TOKEN=$(circuit whoami --reveal auth)
export CIRCUIT_TOKEN="$TOKEN"
circuit whoami                      # confirms the token
circuit dev run --hosted backend --wallet <address> # runs without a saved config

RPC URLs (local mode)

circuit dev run (local mode) needs RPC URLs to broadcast transactions. The CLI ships no defaults — public RPCs are rate-limited and fail unpredictably under real workloads, so explicit configuration is required. Persistent overrides live in ~/.config/circuit/rpc.toml:

[rpc]
"ethereum:1"   = "https://eth-mainnet.alchemyapi.io/v2/KEY"
"ethereum:137" = "https://polygon-mainnet.alchemyapi.io/v2/KEY"
"solana"       = "https://devnet.helius-rpc.com/?api-key=..."

Network IDs follow the canonical wire format: ethereum:<chainId> for EVM, bare solana for Solana. Per-call override via --rpc <networkId>=<url> (repeatable).

​Commands

​Global Flags

​circuit new Flags

​circuit dev run Flags

​circuit dev unwind Flags

​circuit check Flags

​circuit publish Flags

​circuit whoami Flags

​circuit check Output

​File Exclusion (Publish)

​Environment Variables

​Auth Storage

​CI / headless auth

​RPC URLs (local mode)