Skip to main content

​
Create New Agent

Create a new agent project from a template.
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, index, hyperliquid). Skips the template prompt.
  • --path <path>: Output directory path. Defaults to ./<agent-name>.
Prompts (interactive mode):
  1. Template selection (basic, yield, index, 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.

​
Pull Agent Builder Chat

Download an Agent Builder chat workspace to your machine.
The Agent Builder’s Continue locally button copies a one-line installer command that runs this for you:
circuit pull requires login, fetches the current workspace files for a chat you own, writes them into ./<agent-name>/, and installs dependencies with Bun or uv. It refuses to write into a non-empty directory. Flags:
  • --path <path>: Output directory path. Defaults to ./<agent-name>.
Output:
  • Prints the result fields (chatId, name, language, directory, projectDir, fileCount) as key: value lines; --json serializes the same.

​
Run Agent Locally

Test your agent locally by executing its run function 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.
Your code still runs locally with circuit run. Pass --hosted engine to keep running your local code but borrow Circuit’s hosted stack - a dev harness for catching contract/funding issues without deploying:
--hosted engine routes the SDK’s primitive calls through Circuit’s hosted engine - sessions, policy, KMS signing, funding, real wallet selection - while your agent code and orchestration stay local. Agent Builder validation uses --dry-run, so it does not need a hosted session. Omit --hosted for a fully local run. A --dry-run may use either execution mode because it journals writes without effects. Without --dry-run, the embedded engine supports auto only: it executes writes immediately and has no hosted suggestion store or approval UI. If --mode manual is passed, or manual is the first allowedExecutionModes entry, the CLI rejects a non-dry-run embedded execution before authentication, funding, dependency installation, or agent spawn. Use --hosted engine or --upload for manual mode.

​
Run it the way production does (--upload)

--hosted is a local dev harness - it never uploads. To run your agent the way the platform actually runs it, pass --upload:
This auto-uploads your current code, starts through the same headless operation as the web app’s Start button, and tails the exact first admitted run to a durable success or failure. Only then does the CLI stop the session, release its allocation, and admit the best-effort unwind. A failed agent run exits nonzero after that cleanup. If the start response or CLI process is lost, running the same command again resumes the persisted start identity instead of allocating twice. It’s a separate run target from --hosted, not a dev-harness mode - an uploaded run always uses the hosted engine - so the two can’t be combined.

​
Dry run

Pass --dry-run to exercise your agent without executing anything onchain:
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 or --upload. In manual mode it follows the manual branch, journals writes, and warns that approvals are not simulated. Each dry-run invocation receives an empty allocation. [startingAsset] declares a requirement, not granted capital, and a journaled request is not evidence that a balance or position changed. Use --hosted engine when the run must exercise allocation-dependent behavior against a real session. Raw signAndSend / Solana transactions and venue orders are all journaled without a state projection. Flags:
  • --hosted engine: Run your local code against Circuit’s hosted stack (omit for fully local - see above). To run the way the platform actually runs the agent, use --upload instead (separate target, mutually exclusive with --hosted). On first use, the CLI opens a browser to authorize a wallet-scoped signing permit with your passkey; the hosted engine then signs everything server-side through Circuit’s policy engine - EVM transactions and messages, EVM swaps (including EIP-712 permits), Solana transactions, and Polymarket / Hyperliquid orders - the same operations the web app signs.
  • --path <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address>: Pick a specific local keystore wallet (embedded mode) or hosted wallet (--hosted engine) by address.
  • --keystore <path>: (Embedded 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 or --upload. See Dry run above.
  • --mode <mode>: Set the execution mode (auto or manual). Embedded execution accepts only auto. Under --dry-run, manual keeps the agent’s configured branch but journals writes and warns that approvals are not simulated. Hosted targets capture manual suggestions for approval. Runs default to the first entry in allowedExecutionModes; on a resumed hosted session the mode changes only when --mode is passed explicitly, so a replayed command does not reapply the config default.
  • --amount <amount>: (--hosted engine or --upload only) Exact raw token-unit allocation for a new session. The command commits only after the recorded wallet quantity covers it; the agent’s minimumAmount is a recommendation, not a start requirement. 0 starts without capital. Omit it when resuming an active session; change an active allocation through top-up.
  • --var KEY=VALUE: Override/add env vars for this run (repeatable). Merged with .env file; CLI flags take precedence.
  • --rpc <networkId>=<url>: (Embedded 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.
Embedded 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. If the agent declares a [startingAsset] with a non-zero minimumAmount, funds the picked wallet into it from your other holdings when short - one swap at a time, through the same start-funding logic the hosted platform uses. Local hard-fails before the agent starts (rather than warning and continuing) when it can’t make the wallet start-ready:
    • Not enough native gas - local does not auto-fund gas. Top up a little native gas on the agent’s network and re-run.
    • An unsupported starting-asset shape - a Solana starting asset, a native starting asset, or a non-EVM network. Run these with --hosted engine, which supports them.
    • No fundable source for the required asset - add the required asset (or a token that can swap into it), or lower the allocation.
  4. Loads environment variables from .env and --var overrides.
  5. Resolves settings from circuit.toml defaults and --setting overrides.
  6. Spawns the agent process and dispatches SDK primitive calls back to the CLI over a local socket.
  7. Streams agent logs to stdout.
Embedded 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 engine):
  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. Checks for an existing session or creates a new one
  5. Validates starting asset balance
  6. Starts the agent server locally with env vars and settings injected
  7. Sends an execute request with session data
  8. Streams logs to your terminal
  9. Stops the server process after execution completes
circuit run --hosted engine stages the exact file set that would be uploaded into an OS temporary directory before starting the agent, so missing workspace files fail before production. .circuit remains reserved for CLI-managed logs, memory, and typings; do not place agent source files there. Transaction diagnostics: Each transaction attempt prints a diagnostic line. Successful broadcasts include an explorer URL when one is known:
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. Local source: --hosted engine borrows hosted wallets and signing while the staged agent process stays local. It does not upload or replace the agent’s runnable content. For details on how run and unwind are called, see Execution Model.

​
Unwind Agent

Execute your agent’s unwind function to close out positions.
By default this invokes unwind locally with empty positions - the agent’s unwind logic discovers what to close from onchain state via the local RPC. Pass --hosted engine to instead read open positions from a running hosted session and close them through Circuit’s policy/signing path:
Or --upload to dispatch the unwind to Circuit’s hosted sandbox runner (the agent’s unwind runs remotely on a wallet with an active session); the CLI tails it to completion. To test the capital-free branch of your unwind logic, run it in dry-run mode:
unwind --dry-run receives an empty allocation and journals its requested writes. It does not invent positions from an earlier command. Use --hosted engine to exercise the close loop against a running session’s real observed allocation. See Dry run above. Flags:
  • --hosted engine: Dev harness - unwind your local code while borrowing hosted services: reads open positions from a running hosted session and closes them through Circuit’s policy/signing path. Omit for fully local.
  • --upload: Dispatch the unwind to Circuit’s hosted sandbox runner (runs remotely) and tail it to completion. A separate run target from --hosted; mutually exclusive with it.
  • --dry-run: Journal unwind()’s writes instead of executing them. Requests do not manufacture allocation state. Cannot be combined with --hosted or --upload.
  • --path <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address>: Pick a specific local keystore wallet (embedded mode) or hosted wallet (--hosted engine / --upload) by address.
  • --keystore <path>: (Embedded 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>: (Embedded mode) override the RPC URL for a network for this unwind (repeatable).
unwind always runs in auto mode, so it does not accept --mode, --amount, or --setting. Hosted-mode steps (--hosted engine):
  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. Stops the session and releases its virtual allocation atomically, preserving the closing allocation
  7. Starts the agent server locally with env vars and settings injected
  8. Sends a best-effort unwind request with session data and the closing allocation
  9. Streams logs to your terminal
  10. Reports the unwind outcome without changing the already-completed stop
Without --hosted engine, unwind uses only local keystore wallets and invokes unwind 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):
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.
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 plan contract - when a real plan is present (missing or untouched starter templates pass), it must carry all five sections (## Summary, ## What it is, ## How it works, ## Strategy, ## Risks) with ## What it is rows matching the circuit.toml category’s labels; errors name exactly which section or **Label:** row is missing
  • 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, upload. The CLI is long-flag only - there are no single-character aliases.