Skip to main content

​
Commands

CommandDescription
circuit signinAuthenticate via browser (details)
circuit signoutClear stored session (details)
circuit whoamiShow current user (details)
circuit newCreate new agent project (details)
circuit runExecute agent locally (details)
circuit unwindUnwind positions and end session (details)
circuit checkValidate project offline (details)
circuit publishPublish to Circuit infrastructure (details)
circuit wallet listList available wallets (details)
circuit wallet importImport a test wallet (details)

​
Global Flags

Available on all commands:
FlagShortDescription
--path <path>-pAgent project directory (default: current directory)
--format <mode>-fOutput format: text (default), json, or stream-json
--help-hShow command help

​
circuit new Flags

FlagShortValuesDescription
--language-ltypescript, pythonSkip language prompt
--name-nany stringSkip name prompt
--template-tbasic, yield, polymarket, hyperliquidSkip template prompt

​
circuit run Flags

FlagShortDescription
--wallet <address>-wWallet address (skips prompt)
--mode <mode>-mauto or manual (default: first in allowedExecutionModes)
--amount <amount>-aToken amount in smallest unit
--env KEY=VALUE-eSet/override env var (repeatable)
--setting KEY=VALUE-sOverride a circuit.toml setting (repeatable). Required for settings marked required = true.
--local-sdk-dependencies-lSkip automatic dependency installation
--port <port>Fixed port for the agent server (skips automatic port selection)

​
circuit unwind Flags

FlagShortDescription
--wallet <address>-wWallet address (skips prompt)
--env KEY=VALUE-eSet/override env var (repeatable)
--setting KEY=VALUE-sOverride a circuit.toml setting (repeatable). Required for settings marked required = true.
--local-sdk-dependencies-lSkip automatic dependency installation
--port <port>Fixed port for the agent server (skips automatic port selection)

​
circuit check Flags

FlagShortDescription
--env KEY=VALUE-eSet/override env var for validation (repeatable)

​
circuit publish Flags

FlagShortDescription
--env KEY=VALUE-eSet/override env var (repeatable)

​
circuit whoami Flags

FlagShortDescription
--show-auth-aPrint base64 auth token for CI/CD

​
circuit check Output

Validates offline (no auth required):
  • Config structure (valid circuit.toml)
  • Entry point exists (index.ts or main.py)
  • Handler export (agent.getExport() or agent.get_handler())
  • SDK version pinning
  • Environment variable cross-referencing
  • TypeScript typecheck (tsc --noEmit on index.ts; catches hallucinated SDK methods, unknown imports, type errors). Skipped with a warning if node_modules is missing — run bun install first.
  • Python syntax check (py_compile on main.py; catches parse errors). Uses .circuit-venv/bin/python3 when present, otherwise system python3.

​
File Exclusion (Publish)

Automatically excluded from uploads:
CategoryPatterns
Version control.git/**, .svn/**
Dependenciesnode_modules/**, dist/**, venv/**, __pycache__/**
Secrets*.key, *.pem
IDE.vscode/**, .idea/**, *.swp
Build artifactscoverage/**, .pytest_cache/**, .cache/**
Lock filespackage-lock.json, yarn.lock, pnpm-lock.yaml
OtherDockerfile, docker-compose.yml, *.md, *.sh, *.log, .DS_Store
Additional patterns via filesToExclude in circuit.toml.

​
Environment Variables

  • Source: .env in project root + --env CLI flags (flags take precedence)
  • Supported commands: run, unwind, check, publish
  • Local execution (run, 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 at ~/.config/circuit/auth-production.json after circuit signin.

​
CI / headless auth

Set CIRCUIT_SESSION_TOKEN to a sealed session token to skip circuit signin entirely. The CLI’s authManager reads this environment variable before looking for a config file, so every command works the same way whether the token came from ~/.config/circuit/auth-production.json or from the environment. Useful for CI, Docker, and automation contexts where interactive browser sign-in isn’t available. 
export CIRCUIT_SESSION_TOKEN="<base64-sealed-token>"
circuit whoami          # confirms the token
circuit run --wallet … # runs without a saved config