Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Create New Agent

Create a new agent project from a template. 
circuit new
Flags:
  • --language <lang> / -l <lang>: Project language (typescript or python). Skips the language prompt.
  • --name <name> / -n <name>: Agent name. Skips the name prompt.
  • --template <template> / -t <template>: Template to use (basic, yield, polymarket, hyperliquid). Skips the template prompt.
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
  • AI assistant context files (AGENTS.md and CLAUDE.md)
Output:
  • Prints project directory path and next steps

​
Run Agent Locally

Test your agent locally by executing its runFunction against a wallet from the local encrypted vault.
Make sure all required packages are installed via uv sync (Python) or bun install (TypeScript) before running. Run circuit wallet add first to put a signing wallet in the vault.
circuit dev run
Pass --hosted to instead route through Circuit’s hosted runtime (sessions, policy, funding, real wallet selection): 
circuit dev run --hosted
Flags:
  • --hosted: Execute against the hosted runtime instead of pure local mode. Required for in-IDE agent-builder workflows.
  • --path <path> / -p <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address> / -w <address>: Pick a specific wallet from the keystore (local mode) or your hosted wallets (--hosted) by address.
  • --keystore <path>: (Local mode) override the keystore vault file location. Defaults to ~/.config/circuit/keystore.enc.
  • --mode <mode> / -m <mode>: (--hosted only) Set the execution mode (auto or manual). Defaults to the first entry in allowedExecutionModes.
  • --amount <amount> / -a <amount>: (--hosted only) Token amount to allocate in smallest unit (should be greater than minimumAmount).
  • --env KEY=VALUE / -e KEY=VALUE: Override/add env vars for this run (repeatable). Merged with .env file; CLI flags take precedence.
  • --setting KEY=VALUE / -s KEY=VALUE: Override a setting value defined in circuit.toml (repeatable). See Settings below.
  • --local-sdk-dependencies / -l: Skip automatic dependency installation before running.
Local mode (default):
  1. Unlocks the keystore vault (password prompt) 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 (or, for hosted-wallet vault entries, a permit-bearer-authed signer that calls /v1/sign), filesystem-backed logs/memory at <projectDir>/.circuit/.
  3. Loads environment variables from .env and --env overrides.
  4. Resolves settings from circuit.toml defaults and --setting overrides.
  5. Imports the agent module and calls its runFunction(agent) directly in-process.
  6. Streams agent logs to stderr.
Hosted mode (--hosted):
  1. Loads environment variables from .env and --env 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. Uploads your latest agent code (soft publish)
  5. Warns if the version in circuit.toml has not been bumped since the last publish (skipped on first publish)
  6. Checks for an existing session or creates a new one
  7. Validates starting asset balance
  8. Starts the agent server locally with env vars and settings injected
  9. Sends an execute request with session data
  10. Streams logs to your terminal
  11. Stops the server process after execution completes
circuit dev run --hosted 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. 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. Version warning: If the version in your circuit.toml is not newer than the latest published version on Circuit, you’ll see a warning reminding you to bump the version before your next circuit publish. This is a warning only — it does not block the run. In --format json mode, the warning is surfaced as a versionWarning object with localVersion and latestVersion fields. For details on how runFunction and unwindFunction are called, see Execution Model.

​
Unwind Agent

Execute your agent’s unwindFunction to close out positions. 
circuit dev 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 to instead read open positions from a running hosted session and close them through Circuit’s policy/signing path: 
circuit dev unwind --hosted
Flags:
  • --hosted: Execute against the hosted runtime instead of pure local mode.
  • --path <path> / -p <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address> / -w <address>: (--hosted only) Specify the wallet address to unwind instead of being prompted.
  • --env KEY=VALUE / -e KEY=VALUE: Override/add env vars for this unwind (repeatable). Merged with .env file; CLI flags take precedence.
  • --setting KEY=VALUE / -s KEY=VALUE: Override a setting value defined in circuit.toml (repeatable). See Settings below.
  • --local-sdk-dependencies / -l: Skip automatic dependency installation before running.
Hosted-mode steps (--hosted):
  1. Loads environment variables from .env and --env 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

​
Settings

circuit dev run and circuit dev unwind inject your circuit.toml settings into the agent context. Default values for optional settings are included automatically — no flags needed. Settings marked required = true in circuit.toml have no default value. You must provide them via --setting on every invocation — both commands will fail if any required settings are missing and no --setting override is provided. To override individual values for a single invocation, use --setting KEY=VALUE (repeatable): 
circuit dev 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 command. Running circuit dev unwind separately requires repeating the same --setting flags — otherwise TOML defaults are used. This matches --env 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 offline — no authentication required. 
circuit check
Flags:
  • --format <mode> / -f <mode>: Output format: text (default), json (structured result), or stream-json (NDJSON events).
  • --path <path> / -p <path>: Path to agent project directory (defaults to current directory).
  • --env KEY=VALUE / -e KEY=VALUE: Override/add env vars for validation (repeatable). Merged with .env file; CLI flags take precedence.
Checks performed:
  • 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
  • Files to upload listing
  • TypeScript typecheck via project tsconfig.json, or Python syntax check

​
Global Flags

The CLI parser supports these global flags:
  • --path <path> / -p <path>: Path to agent project directory (defaults to current directory).
  • --format <mode> / -f <mode>: Output format: text (default), json (structured result), or stream-json (NDJSON events).
  • --help / -h: Show help for the command.