Create New Agent
circuit new --name <name> [--path <path>] scaffolds TypeScript source, configuration, description, a dependency manifest, runtime configuration, SDK types and assistant instructions. The default directory derives from the name; nonempty directories are rejected. Output contains agentId, name, directory, and projectDir; --json emits one document. .circuit/ is reserved for CLI state, never agent source. circuit check installs dependencies, writes the lockfile and regenerates circuit-sdk.d.ts and circuit-settings.d.ts.
Pull Agent Workspace
circuit pull <workspaceId> [--path <path>] downloads an owned builder Workspace and installs its dependencies with the CLI’s built-in Bun. Sign-in is required. It refuses nonempty destinations and reports workspaceId, name, directory, projectDir, and fileCount. Builder’s Continue locally runs curl -fsSL https://api.circuit.org/dev | bash && ~/.local/bin/circuit auth login && ~/.local/bin/circuit pull <workspaceId>: it installs the CLI, signs you in through the normal browser/passkey flow (the command carries no credential), and pulls the Workspace into ./<agent-name>/.
Discover capabilities
circuit capabilities --resource index --json lists version-matched resources and the SDK digest. Read sdk for TypeScript declarations, config for the canonical configuration template and its executable validator (circuit check), networks for the complete compact network list with canonical dollar and wrapped-native assets, network/<id> (for example network/ethereum:5042) for one network’s full configuration, data/<name> for data discovery, engine/<name> for wire inputs/results, and action/<kind> for the money action’s SDK method, input and operationResult, derived from the action owner; operationResult describes the successful operation’s nested result, while the full operation envelope is in the SDK types, and a contract with an unsupported runtime predicate fails generation explicitly. JSON responses are compact and retain every field; capability responses contain an ordered resources array of {resource,data} entries, without character pagination. Repeat --resource to request related schemas in one command, for example circuit capabilities --json --resource action/evmTx --resource engine/moneyPrepare --resource engine/moneyAction. Any unknown resource fails the command. JSON Schema cannot express every custom refinement; the SDK types and runtime validators remain authoritative.
Run Agent Locally
circuit run --wallet <name-or-address> runs temporary local code with a local encrypted-vault wallet and embedded engine. --target hosted-engine runs it with the selected hosted wallet, sessions, permit and KMS-F signing and no upload: the session uses local circuit.toml configuration, never changes the published agent, has no server triggers and runs only from the CLI (Top up, Run now and Resume are unavailable, the next circuit run clears a pause, and changing its allocated amount means stopping and running again with --amount). --target hosted uploads current code, starts a recurring hosted session through the shared Start operation and tails the first run; the session stays active. circuit run --simulated paper trades temporary local code on live markets, with no wallet, keys or funds.
Preparation copies the upload file set, installs locked dependencies without scripts, strictly compiles against runtime-provided SDK declarations with a trusted compiler, then checks the production bundle and run export. It ignores project compiler settings. Local execution, hosted execution and replay run the prepared ESM bundle. Hosted runs execute the bundle prepared at upload; a later SDK change does not recompile it, so code that relies on a changed SDK surface fails when it calls it. Excluded files are unavailable. Preparation finishes before session changes; the temporary copy is removed afterward. Hosted-engine runs record the prepared artifact’s SHA-256 hash without uploading it. NDJSON protocol 3 distinguishes the CLI invocationId from the admitted runId; run.started identifies the session before completion or failure.
Embedded execution keeps the project’s sessions, their starting allocations and its operations in the embedded engine database in .circuit/engine, and reconstructs allocation from them and durable venue account history the way hosted sessions do. SDK money writes execute immediately; data.* returns empty rows without contacting Circuit, except that --simulated reads Circuit’s public market data. A paper run trades a paper account whose walletAddress is its own keyless address: swaps fill at the live executable quote, venue orders against the live book and one-minute bars, Polymarket orders against the live book with redemptions paid at resolution, and transfers, raw transactions and signing fail. Explicit external reads are separate. Hosted execution resolves the named wallet, validates funding, creates or resumes a session, and routes calls to the hosted engine. First use requests a wallet-scoped passkey permit. See Holdings. An uploaded run tails its first run to durable completion and exits nonzero on failure. The session keeps its allocation and triggers after the CLI exits, including on failure or interruption. Use Stop or circuit stop --target hosted --wallet <name-or-address> to stop it. Repeating an interrupted command resumes its persisted start identity; starting again on an active wallet is rejected.
Run and stop flags
Embedded runs default to public RPC endpoints. Override one per invocation with the repeatable
--rpc <networkId>=<url>, or persistently with "<networkId>" = "<url>" lines under [rpc] in ~/.circuit/rpc.toml. Network IDs are ethereum:<chainId> for a supported EVM chain or solana; any other ID is rejected.
Embedded swaps use the same providers as hosted execution. Supply SWAPS_UNISWAP_API_KEY, SWAPS_JUPITER_API_KEY, SWAPS_RELAY_API_KEY, SWAPS_NEAR_INTENTS_API_KEY, or both SWAPS_ACROSS_API_KEY and SWAPS_ACROSS_INTEGRATOR_ID where required. Credentials serve quotes/execution and are never persisted in operation records. Transaction diagnostics include explorer links where available; run --json emits NDJSON with diagnostics in output envelopes.
Stop Agent
circuit stop ends the project’s active local session, wallet or paper, and deletes its session facts and memory; a --wallet must match that session. With --target hosted-engine or --target hosted and --wallet <name-or-address> it stops that wallet’s hosted session. Stop runs no agent code (execution model).
Backtest Agent
circuit backtest [--from <ISO>] [--to <ISO>] [--usd <amount>] [--setting KEY=VALUE] [--output <path>] --json replays the project against recorded Hyperliquid, Lighter or Lighter Robinhood markets without a wallet, account or network writes. An agent that starts from HyperCore USDC, Lighter USDC or Lighter Robinhood USDG replays on that venue, and every venue trigger must be on it. A news trigger wakes run at the minute each matching item arrived, which limits the window to the last 7 days. A market’s history loads the first time the agent orders it, and Lighter orders pin against Lighter’s current size, price and minimum rules. The agent module evaluates once per replay, so unlike hosted runs, module-level variables persist between replayed runs; keep state in agent.memory. Its triggers wake run on a deterministic replay clock; positions still open at the end of the window are marked to market. Every agent.data read is answered as of that clock: candles and mids load once and are sliced per read, and other reads are answered for their own instant and, once the same query repeats, in batches covering the scheduled runs. Orders are sized like paper sessions’ orders and filled in memory by the same paper venue rules: perpetual orders fill at the current one-minute open, or the last traded close in a minute without trades, or, for resting orders, once a later minute trades through the limit and the account has margin for the fill, with the reported fee, slippage, shared per-minute volume and leverage assumptions; positions pay funding at each hour’s opening price. The account is liquidated at a minute’s close when its equity there falls below maintenance margin. Cross leverage changes apply to margin; other money actions, spot orders, outside requests and a missing recorded funding settlement fail loudly; a failed run is reported, its failures are grouped in the report, and the replay continues. The window defaults to the last seven days, or the seven days before --to when it is given; --to defaults to the latest hour the venue’s recorded candles and funding cover, with 1000 USD. Without --json it prints the window, the result, trades, fees and funding, and any warning: failed runs with their most frequent reasons, no trades with the agent’s most frequent messages, liquidations, and resting orders that count as filled whenever the price trades through them. When most runs failed it prints no result. --json prints the compact Builder report and --output writes the untruncated result. The replay fails two minutes after it starts. Results describe the selected historical period and do not predict future performance.
Validate Agent Project
circuit check [--path <path>] [--artifact <path>] --json validates without executing agent code or contacting Circuit; dependency installation can contact the registry. It checks root configuration, settings, starting inventory, required project files and a production-form build. --artifact writes the validated production TAR after all checks pass; keep it outside authored source, such as .builder/verified.tar. A present DESCRIPTION.md must pass the same Thesis, Strategy and Exposure rules upload enforces. The CLI installs dependencies without scripts, regenerates SDK types and runs the project compiler with a CLI-owned strict configuration over collected TypeScript source. No project tsconfig.json is needed or read by the check. A generated type assertion verifies a callable run export. Upload repeats production preparation from pinned source. Invalid projects exit nonzero; passing check establishes structural validity, not strategy correctness.
Command Inputs and Global Flags
Supply required flags and use positional arguments only where shown in the command syntax. Explicit secret-prompt flags require an interactive terminal. Commands that require authentication check it before prompting. Input is hidden; Enter submits each value. Ctrl+C exits with code 130 without saving or writing JSON. See authentication to sign in. All wallet selectors use--wallet <name-or-address>; see wallet selection.
--json emits one document for one-shot commands and NDJSON for run. --env production|staging|local overrides CIRCUIT_ENV and defaults to production. --assistant <name> overrides CIRCUIT_ASSISTANT and acts under that assistant’s saved sign-in. --help shows command help; --version reports the CLI version. Flags have no short aliases. Project commands accept --path; new and pull treat it as the output directory. circuit check --locked --json validates against the existing lockfile without updating it. A project still holding a retired local session format fails with its path; finish that session with the previous CLI, move the files aside, and start a new session.