CLI Quick Reference

Commands

Command	Description
`circuit new`	Create new agent project (details)
`circuit pull <chatId>`	Download an Agent Builder chat locally (details)
`circuit check`	Validate project offline (details)
`circuit run`	Execute agent locally; `--hosted engine` to use the hosted engine (details)
`circuit unwind`	Unwind agent locally; `--hosted engine` to use the hosted engine (details)
`circuit upload`	Upload to Circuit infrastructure; `--enable=true\|false` to set visibility while publishing (details)
`circuit agent list`	List the agents you’ve published, with each one’s enabled state
`circuit auth login`	Authenticate via browser (details)
`circuit auth login --local`	Mint an offline local session for local signing - no browser/account (details)
`circuit auth logout`	Clear stored credentials (details)
`circuit auth whoami`	Show current user (details)
`circuit auth token`	Print your bearer token for CI capture (details)
`circuit kraken connect`	Connect a Kraken API credential for uploaded agents
`circuit kraken list`	List connected Kraken credentials
`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	Description
`--json`	Machine-readable JSON: a single document for one-shot commands, a live NDJSON event stream for `run`/`unwind`
`--env <env>`	Target deployment: `production` (default), `staging`, or `local`. Takes precedence over `CIRCUIT_ENV`.
`--help`	Show command help
`--version`	Show version

The CLI is long-flag only - there are no single-character aliases (not even -h/-v). --path (agent project directory, default: current dir) is on the project commands - new, pull, check, run, unwind, upload. --var KEY=VALUE (inject an environment variable into the agent, repeatable) is on upload, run, unwind.

`circuit new` Flags

Flag	Values	Description
`--language`	`typescript`, `python`	Skip language prompt
`--name`	any string	Skip name prompt
`--template`	`basic`, `yield`, `index`, `hyperliquid`	Skip template prompt

`circuit run` Flags

Flag	Description
`--hosted engine`	Borrow Circuit’s hosted stack while your code runs locally: route the SDK’s primitive calls through the hosted engine (sessions, policy, KMS signing, funding). Omit for a fully local run. Does not upload - see `--upload`.
`--upload`	Upload the agent and start it through the web app’s shared headless operation. The CLI waits for that exact first run to finish, then stops/releases the session; an interrupted start resumes from its persisted identity. Mutually exclusive with `--hosted`.
`--dry-run`	Journal every signing / fund-moving write instead of executing it; reads still hit live providers. No keystore, login, or funding needed. A journaled request is not treated as an observed balance or position. Cannot be combined with `--hosted` or `--upload`.
`--wallet <address>`	Local keystore wallet address, or hosted wallet address with `--hosted engine` / `--upload`
`--mode <mode>`	`auto` or `manual` (default: first in `allowedExecutionModes`)
`--amount <amount>`	Initial token allocation in smallest unit (requires `--hosted engine` or `--upload`; active sessions use top-up)
`--var KEY=VALUE`	Set an environment variable for the agent (repeatable)
`--setting KEY=VALUE`	Override a `circuit.toml` setting (repeatable). Required for settings marked `required = true`.
`--keystore <path>`	(Embedded mode) override the keystore vault file location
`--rpc <networkId>=<url>`	(Embedded mode) override a network’s RPC URL (repeatable)

`circuit unwind` Flags

Flag	Description
`--hosted engine`	Borrow Circuit’s hosted stack while your code runs locally: read open positions from a running hosted session and close them through Circuit’s policy/signing path. Omit for a fully local run.
`--upload`	Dispatch the unwind to Circuit’s hosted sandbox runner and tail it to completion. Mutually exclusive with `--hosted`.
`--dry-run`	Journal `unwind()`’s writes instead of executing them. It receives an empty allocation because the harness owns no virtual-allocation fact; use hosted engine mode to unwind real observed positions. Cannot be combined with `--hosted` or `--upload`.
`--wallet <address>`	Local keystore wallet address, or hosted wallet address with `--hosted engine` / `--upload`
`--var KEY=VALUE`	Set an environment variable for the agent (repeatable)
`--keystore <path>`	(Embedded mode) override the keystore vault file location
`--rpc <networkId>=<url>`	(Embedded mode) override a network’s RPC URL (repeatable)

unwind always runs in auto mode, so it has no --mode, --amount, or --setting. run and unwind print one transaction diagnostic per attempt, for example tx confirmed [ethereum:8453]: https://basescan.org/tx/0x... or tx failed [ethereum:8453]: <error>. Under --json these are output event envelopes in the NDJSON stream.

`circuit check` Flags

No command-specific flags - --path (project directory) and the global flags only.

`circuit pull` Flags

Flag	Description
`--path <path>`	Output directory path. Defaults to `./<agent-name>`.

Used by Agent Builder’s Continue locally command:

curl -fsSL https://api.circuit.org/dev | bash -s -- <chatId>

`circuit upload` Flags

Flag	Description
`--var KEY=VALUE`	Set an environment variable for the agent (repeatable)
`--enable=true\|false`	Set the agent’s visibility while publishing; omit to leave it unchanged

`circuit auth token`

Default prints nothing but the bare bearer token (the passkey-signed wire string), so TOKEN=$(circuit auth token) captures it for CI/CD. --json wraps the same value as { "token": "..." }. --decode prints the decoded pre-b64 permit (payload + WebAuthn proof) instead - a local decode, not a verification. circuit auth whoami shows identity + what the token grants, but never the raw token itself.

`circuit kraken`

circuit kraken connect seals a Kraken API credential to your Circuit account. It prompts for Credential label, Kraken API key, and Kraken private key; for headless use, set KRAKEN_CREDENTIAL_LABEL, KRAKEN_API_KEY, and KRAKEN_API_SECRET. By default the credential is connected with read and trade permissions; add --read-only to connect without trade permission. circuit kraken list prints id, label, permissions, and status. Use the id as the credential to select when starting an agent that declares [exchangeCredentials.kraken]; agents that declare trade = true also require minimumAllocationUsd in circuit.toml and a Kraken allocation at start - the user-declared Kraken allocation target for that session. The runtime exposes the selected credential as agent.credentials.kraken.

`circuit check` Output

Validates offline (no auth, no network):

circuit.toml exists at the project root (exactly one)
Config structure (valid circuit.toml fields)
DESCRIPTION.md present (optional)
Project structure - TypeScript (index.ts + package.json + bun.lock) or Python (main.py + pyproject.toml)
Settings definitions
Starting asset ([startingAsset]) configured

circuit check does not run a language type-checker or Python syntax check - your IDE / pre-commit hooks own that. It does provision the environment-provided SDK and install dependencies first, so editors resolve circuit:sdk / circuit_sdk again.

File Exclusion (Upload)

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 uploads require an up-to-date bun.lock.

Environment Variables

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

Auth Storage

Credentials stored in ~/.circuit/auth.toml after circuit auth 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 auth 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 auth token)
export CIRCUIT_TOKEN="$TOKEN"
circuit auth whoami                      # confirms who you are
circuit run --hosted engine --wallet <address> # runs without a saved config

RPC URLs (embedded mode)

Embedded runs use the shared execution adapter’s public RPC endpoints by default. Override them when you need a private provider, deterministic endpoint, or local fork. Persistent overrides live in ~/.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).

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

CLI Quick Reference

Commands

Global Flags

`circuit new` Flags

`circuit run` Flags

`circuit unwind` Flags

`circuit check` Flags

`circuit pull` Flags

`circuit upload` Flags

`circuit auth token`

`circuit kraken`

`circuit check` Output

File Exclusion (Upload)

Environment Variables

Auth Storage

CI / headless auth

RPC URLs (embedded mode)

​Commands

​Global Flags

​circuit new Flags

​circuit run Flags

​circuit unwind Flags

​circuit check Flags

​circuit pull Flags

​circuit upload Flags

​circuit auth token

​circuit kraken

​circuit check Output

​File Exclusion (Upload)

​Environment Variables

​Auth Storage

​CI / headless auth

​RPC URLs (embedded mode)

Commands

Global Flags

`circuit new` Flags

`circuit run` Flags

`circuit unwind` Flags

`circuit check` Flags

`circuit pull` Flags

`circuit upload` Flags

`circuit auth token`

`circuit kraken`

`circuit check` Output

File Exclusion (Upload)

Environment Variables

Auth Storage

CI / headless auth

RPC URLs (embedded mode)