Skip to main content

​
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)
  • AI coding assistant context (AGENTS.md and CLAUDE.md)
Output:
  • Prints project directory path and next steps

​
Run Agent Locally

Test your agent locally by executing the run function.
Make sure all required packages are installed via uv sync (Python) or bun install (TypeScript) before running.
circuit run
Flags:
  • --path <path> / -p <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address> / -w <address>: Specify the wallet address to use instead of being prompted.
  • --mode <mode> / -m <mode>: Set the execution mode (auto or manual). Defaults to the first entry in allowedExecutionModes.
  • --amount <amount> / -a <amount>: 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.
  • --local-sdk-dependencies / -l: Skip automatic dependency installation before running.
How it works:
  1. Loads environment variables from .env and --env overrides
  2. Prompts you to select a wallet from your imported wallets (or uses --wallet flag)
  3. Uploads your latest agent code (soft publish)
  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 injected
  7. Sends an execute request with session data
  8. Streams logs to your terminal
  9. Stops the server process after execution completes
Soft publish: Step 2 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 run and unwind functions are called, see Execution Model.

​
Unwind Agent

Execute your agent’s unwind function on a running session, then end the session. 
circuit unwind
Flags:
  • --path <path> / -p <path>: Run from a specific agent directory instead of the current directory.
  • --wallet <address> / -w <address>: 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.
  • --local-sdk-dependencies / -l: Skip automatic dependency installation before running.
How it works:
  1. Loads environment variables from .env and --env overrides
  2. Fetches your imported wallets that have active sessions for this agent
  3. Prompts you to select a wallet (or uses --wallet flag)
  4. If multiple sessions exist for the wallet, prompts you to select one
  5. Fetches current positions for the session
  6. Starts the agent server locally with env vars injected
  7. Sends an unwind request with session data and positions
  8. Streams logs to your terminal
  9. Ends the session after unwind completes

​
Check Agent Project

Validate your agent project configuration and files offline — no authentication required. 
circuit check
Flags:
  • --json / -j: Output results as JSON.
  • --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

​
Global Flags

The CLI parser supports these global flags:
  • --path <path> / -p <path>: Path to agent project directory (defaults to current directory).
  • --json / -j: Output results as JSON (most useful on check, publish, and whoami).
  • --help / -h: Show help for the command.