Skip to main content

​
Create New Agent

Create a new agent project from a template. 
circuit new
Flags:
  • --language <lang>: Project language (typescript or python). Skips the language prompt.
  • --name <name>: Agent name. Skips the name prompt.
  • --template <template>: Template to use (basic, yield, polymarket, hyperliquid). Skips the template prompt.
  • --path <path>: Output directory path. Defaults to ./<agent-name>.
Prompts (interactive mode):
  1. Template selection (basic, yield, polymarket, hyperliquid)
  2. Language selection (TypeScript or Python)
  3. Agent name (used to generate the directory name)
Creates:
  • A new directory named after the agent name
  • Agent code template (index.ts or main.py)
  • Configuration file (circuit.toml)
  • Description file (DESCRIPTION.md)
  • Dependency file (package.json or pyproject.toml)
  • TypeScript compiler configuration (tsconfig.json) for TypeScript projects
  • TypeScript dependency lockfile (bun.lock) for TypeScript projects
  • Python dependency lockfile (uv.lock) for Python projects
  • AI assistant context files (AGENTS.md and CLAUDE.md)
Output:
  • Prints the result fields (language, name, directory, projectDir, template) as key: value lines; --json serializes the same. Capture the path with circuit new ... --json | jq -r .projectDir.

​
Run Agent Locally

Test your agent locally by executing its runFunction against a wallet from the local encrypted vault.
Generated projects install dependencies automatically. If you edit dependencies manually, run uv sync (Python) or bun install (TypeScript) before running. Run circuit wallet add first to put a signing wallet in the vault.
circuit run
Pass --hosted <level> to run against Circuit’s hosted stack instead. The level names how far up the stack to host, and each level includes the ones below it: 
circuit run --hosted signing   # KMS signing only — local everything else
circuit run --hosted execution   # + hosted execution (sessions, policy, funding)
circuit run --hosted runtime   # + agent code runs in the hosted Lambda
  • --hosted signing keeps everything local (in-process orchestration, RPC reads, memory) but signs transactions with your Circuit KMS wallet instead of a local keystore key — so you can iterate locally against your real funded wallet without managing a local key.
  • --hosted execution also routes the SDK’s primitive calls through Circuit’s hosted execution (sessions, policy, funding, real wallet selection). Required for in-IDE agent-builder workflows.
  • --hosted runtime also runs the agent entirely in Circuit’s hosted runtime, the way the web app’s Start button does — it auto-publishes your current code, dispatches one run to the hosted runtime, and tails it to completion.
Omit --hosted for a fully local run.

​
Dry run

Pass --dry-run to exercise your agent without executing anything on-chain: 
circuit run --dry-run
In dry-run mode every signing or fund-moving call your agent makes — signAndSend, signMessage, swap.execute, Polymarket / Hyperliquid orders, transfers — is journaled to the run log and answered with a stand-in result instead of being signed and broadcast. Read calls (swap.quote, balances, positions, prices) still hit live providers, so your agent branches on real data and runs exactly the path it would in production — it just never moves funds or touches a key. Because nothing is signed, a dry run needs no keystore, no login, and no funding — it’s the fastest way to see what an agent would do. The wallet it operates as comes from --wallet <address> (so reads are scoped to a real wallet); omit it and reads run against a placeholder address. --dry-run is local-only and cannot be combined with --hosted. Flags:
  • --hosted <level>: Run against Circuit’s hosted stack up through signing, execution, or runtime (omit for fully local; each level includes the ones below it — see above). On first use of any hosted level, the CLI opens a browser to authorize a wallet-scoped signing permit with your passkey. Hosted signing covers the full signing surface — EVM transactions and messages, EVM swaps (including EIP-712 permits), Solana transactions, and Polymarket / Hyperliquid orders — the same operations the web app signs through Circuit’s policy engine.
  • --path <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address>: Pick a specific local keystore wallet (local mode) or hosted wallet (--hosted execution) by address.
  • --keystore <path>: (Local mode) override the keystore vault file location. Defaults to ~/.circuit/local/keystore.
  • --dry-run: Journal every signing / fund-moving write instead of executing it; reads still hit live providers. Needs no keystore, login, or funding. Cannot be combined with --hosted. See Dry run above.
  • --mode <mode>: Set the execution mode (auto or manual). Defaults to the first entry in allowedExecutionModes.
  • --amount <amount>: (--hosted execution/runtime only) Token amount to allocate in smallest unit (should be greater than minimumAmount).
  • --var KEY=VALUE: Override/add env vars for this run (repeatable). Merged with .env file; CLI flags take precedence.
  • --rpc <networkId>=<url>: (Local mode) override the RPC URL for a network for this run (repeatable).
  • --setting KEY=VALUE: Override a setting value defined in circuit.toml (repeatable). See Settings below.
  • --local-sdk-dependencies: Skip automatic dependency installation before running.
Local mode (default):
  1. Unseals the keystore vault (no password — it’s sealed under the local identity) and picks a wallet that matches the agent’s walletType — single match implicit, multiple match interactive picker, or --wallet <address> to bypass.
  2. Builds local primitives — viem-based EVM signer for local EVM keys or Solana Web3 signing for local Solana keys, plus filesystem-backed logs/memory at <projectDir>/.circuit/.
  3. Loads environment variables from .env and --var overrides.
  4. Resolves settings from circuit.toml defaults and --setting overrides.
  5. Spawns the agent process and dispatches SDK primitive calls back to the CLI over a local socket.
  6. Streams agent logs to stderr.
Local mode only reads local keystore wallets and does not call the Circuit API. Hosted mode selects wallets from your Circuit account through the API. Hosted mode (--hosted execution):
  1. Loads environment variables from .env and --var overrides
  2. Resolves settings from circuit.toml defaults and --setting overrides
  3. Prompts you to select a wallet from your imported wallets (or uses --wallet flag)
  4. Pins the run to the exact local source you’re about to execute by registering it as the agent’s dev version — so a brand-new, never-published agent can be run, and a previously-published agent’s dev run uses the code in front of you rather than its published version
  5. Checks for an existing session or creates a new one
  6. Validates starting asset balance
  7. Starts the agent server locally with env vars and settings injected
  8. Sends an execute request with session data
  9. Streams logs to your terminal
  10. Stops the server process after execution completes
circuit run --hosted execution stages the exact file set that would be uploaded for deploy into <agent-dir>/.circuit/ before starting the agent. Treat .circuit as a reserved CLI-managed directory and do not place agent source files there or point filesToInclude into it. Transaction diagnostics: Each transaction attempt prints a diagnostic line. Successful broadcasts include an explorer URL when one is known: 
tx confirmed [ethereum:8453]: https://basescan.org/tx/0xabc...
tx failed [ethereum:8453]: Policy rejected: daily spend limit exceeded
If an agent retries after failures, each attempt is shown separately. Under --json (run/unwind emit an NDJSON event stream), these diagnostics are output envelopes on stdout and raw stderr stays empty. Soft publish: In hosted mode, step 4 uploads your code to Circuit for the dev session only. Unlike circuit publish, a soft publish does not create a new versioned release — it temporarily makes your latest code available for the local execution. For details on how runFunction and unwindFunction are called, see Execution Model.

​
Unwind Agent

Execute your agent’s unwindFunction to close out positions. 
circuit unwind
By default this invokes unwindFunction locally with empty positions — the agent’s unwind logic discovers what to close from on-chain state via the local RPC. Pass --hosted execution to instead read open positions from a running hosted session and close them through Circuit’s policy/signing path: 
circuit unwind --hosted execution
Or --hosted runtime to dispatch the unwind to Circuit’s hosted runtime (the agent’s unwindFunction runs remotely on a wallet with an active session); the CLI tails it to completion. Flags:
  • --hosted <level>: Run against Circuit’s hosted stack — execution reads open positions from a running hosted session and closes them through Circuit’s policy/signing path; runtime dispatches the unwind to the hosted runtime (runs remotely) and tails it to completion. (signing behaves like local unwind with KMS signing.) Omit for fully local.
  • --path <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address>: Pick a specific local keystore wallet (local mode) or hosted wallet (--hosted execution) by address.
  • --keystore <path>: (Local mode) override the keystore vault file location. Defaults to ~/.circuit/local/keystore.
  • --var KEY=VALUE: Override/add env vars for this unwind (repeatable). Merged with .env file; CLI flags take precedence.
  • --rpc <networkId>=<url>: (Local mode) override the RPC URL for a network for this unwind (repeatable).
  • --local-sdk-dependencies: Skip automatic dependency installation before running.
unwind always runs in auto mode, so it does not accept --mode, --amount, or --setting. Hosted-mode steps (--hosted execution):
  1. Loads environment variables from .env and --var overrides
  2. Resolves settings from circuit.toml defaults and --setting overrides
  3. Fetches your imported wallets that have active sessions for this agent
  4. Prompts you to select a wallet (or uses --wallet flag)
  5. If multiple sessions exist for the wallet, prompts you to select one
  6. Fetches current positions for the session
  7. Starts the agent server locally with env vars and settings injected
  8. Sends an unwind request with session data and positions
  9. Streams logs to your terminal
  10. Ends the session after unwind completes
Without --hosted execution, unwind uses only local keystore wallets and invokes unwindFunction with empty positions.

​
Settings

circuit run and circuit unwind inject your circuit.toml settings into the agent context. Default values for optional settings are included automatically — no flags needed. Only circuit run accepts --setting overrides; circuit unwind always uses the circuit.toml defaults. Settings marked required = true in circuit.toml have no default value. You must provide them via --setting on every circuit run invocation — the command fails if any required setting is missing and no --setting override is provided. To override individual values for a single circuit run invocation, use --setting KEY=VALUE (repeatable): 
circuit run --setting risk_level=high --setting buy_amount_usd=100 --setting api_key=sk-abc123
Resolution order: circuit.toml default (if optional) → --setting override. Required settings have no default and must be provided via --setting. The CLI validates overrides against your circuit.toml definitions:
  • Unknown keys are rejected
  • Values are type-checked (e.g., boolean settings only accept true/false)
  • single_select values must be one of the defined options
  • address values are validated for the agent’s wallet type
Per-invocation scope: Setting overrides apply only to the current circuit run command. This matches --var behavior: .env is the persistent layer for env vars, circuit.toml defaults are the persistent layer for settings.

​
Validate Agent Project

Validate your agent project configuration and files. Validation runs entirely offline — no authentication and no network connection required. 
circuit check
Flags:
  • --path <path>: Path to agent project directory (defaults to current directory).
  • --json: Emit the validation result as one JSON document (exit non-zero when invalid).
Checks performed:
  • circuit.toml exists at the project root (and only 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 (tsc) or Python syntax check — your IDE / pre-commit hooks own that. Before validating, it provisions the environment-provided SDK (circuit-sdk.d.ts for TypeScript, circuit_sdk into .venv for Python) and installs dependencies, so editors resolve circuit:sdk / circuit_sdk again after a fresh clone.

​
Global Flags

These flags are accepted by every command:
  • --json: Emit machine-readable JSON — a single document for one-shot commands, an NDJSON event stream for run/unwind.
  • --env <env>: Target deployment (production (default), staging, or local). Takes precedence over CIRCUIT_ENV.
  • --help: Show help for the command.
  • --version: Show the CLI version.
--path <path> (agent project directory, defaults to current directory) is on the project commands — new, check, run, unwind, publish. The CLI is long-flag only — there are no single-character aliases.