Skip to main content

​
Create New Agent

circuit new --name <name> creates a project. Use --path <path> to override the default ./<agent-name> directory. See command input rules. The project includes index.ts, circuit.toml, DESCRIPTION.md, package.json, tsconfig.json, bun.lock, bunfig.toml (runtime auto-install disabled), circuit-sdk.d.ts, and assistant context (AGENTS.md, CLAUDE.md). Its .gitignore excludes node_modules/ and CLI state in .circuit/. circuit check regenerates SDK typings. Output contains name, directory, and projectDir as key: value lines or the same fields under --json. To capture the path:

​
Pull Agent Workspace

circuit pull <workspaceId> requires login, downloads the current files of a Workspace you own, and installs dependencies with Bun. It writes to ./<agent-name>/ or --path <path> and refuses non-empty directories. Output contains workspaceId, name, directory, projectDir, and fileCount; --json serializes those fields. The Agent Builder’s Continue locally button supplies this installer:

​
Run Agent Locally

circuit run executes the agent’s run function. Choose its execution target:
Generated projects install dependencies automatically. After changing dependencies, run bun install and commit bun.lock before circuit check or circuit run. Embedded live runs require a wallet added with circuit wallet add.
Local execution copies the upload file set into an OS temporary directory, installs production dependencies from the frozen lockfile, validates the index.ts contract, and runs that entrypoint directly. Excluded files are unavailable. --hosted engine records the SHA-256 hash of that exact prepared code and dependencies on the admitted run, without uploading the archive. NDJSON protocol 2 names the CLI invocation invocationId; run.started.data.runId and the final result contain the actual admitted run ID. Preparation finishes before session changes; execution never installs into or modifies the source project, and removes the temporary copy afterward. .circuit/ is reserved for CLI-managed logs, memory, typings, and session facts, not agent source. Embedded live mode unseals the --wallet target, opens .circuit/session.json and its engine.sqlite, and reconstructs agent.allocation from the durable starting allocation and observed operation legs. SDK writes execute immediately under local wallet authority. SDK data.* returns empty rows without contacting Circuit; accepted hosted Circuit reads explicitly used by an agent are separate. Hosted mode resolves the named wallet, resumes or creates its session, validates funding, and routes SDK calls through the hosted engine. The first hosted use opens a browser for a wallet-scoped passkey signing permit. Size autonomous work from the session allocation; see Wallets & Asset Allocation. Every live run and unwind requires --wallet; dry run alone may omit it. The CLI resolves the name or address but does not rank wallets or decide Start readiness. Start checks the selected wallet and exact allocation against live state under the server allocation lock. Agent Builder validation uses circuit check; Test draft creates a real-money test session on a private draft-test agent without changing released code. Use Publish to update the released agent.

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

An uploaded run tails the exact first admitted run to durable success or failure. That durable completion stops the test session, releases its allocation, and admits best-effort unwind. Failed runs exit nonzero after cleanup. If the start response or CLI process is lost, repeating the command resumes its persisted start identity instead of allocating twice. --upload always uses the hosted engine and cannot combine with --hosted.

​
Dry run

Dry-run mode journals wallet transaction creation, message signing, swaps, transfers, and venue orders without signing or broadcasting. Quotes, balances, positions, and prices use live providers. SDK data.* returns empty rows, so data-dependent branches can differ from production. No login or funding is required. --wallet <name-or-address> scopes reads to that wallet; a name unseals the local keystore, while an address needs no keystore. Omit --wallet to use a placeholder. Every invocation has an empty allocation and its own session identity: [startingAsset] declares a requirement, not granted capital, and journaled requests never project balances or positions. Use --hosted engine for allocation-dependent behavior. --dry-run cannot combine with --hosted, --upload, or --amount.

​
Run and unwind flags

Embedded swaps share hosted provider contracts. Supply SWAPS_UNISWAP_API_KEY, SWAPS_JUPITER_API_KEY, SWAPS_RELAY_API_KEY, or both SWAPS_ACROSS_API_KEY and SWAPS_ACROSS_INTEGRATOR_ID. Credentials apply to quotes and execution and are never persisted in operation records. Providers may reject unauthenticated requests or require credentials for Circuit fees. Each transaction attempt prints diagnostics, including an explorer URL for confirmed transactions when available. If agent code retries, each attempt is shown separately. run and unwind with --json emit an NDJSON event stream: diagnostics use output envelopes on stdout and raw stderr remains empty. See Execution Model for entrypoint behavior.

​
Unwind Agent

circuit unwind stops the active project-local session before invoking the agent’s unwind function with its last durable allocation, including successful embedded operation legs. It validates the prepared agent before removing the active session, then deletes session facts and session memory after the agent exits; shared memory remains. An interrupted unwind fails loudly on the next command. circuit unwind --hosted engine executes local code against the named wallet’s running hosted session. --wallet is required. Stopping atomically releases the virtual allocation while preserving the closing allocation for the best-effort unwind. Logs and the outcome do not reverse the completed stop. circuit unwind --upload --wallet <name-or-address> dispatches unwind to the hosted sandbox for the named wallet’s active session and tails completion. circuit unwind --dry-run receives an empty allocation and journals writes; it does not invent positions from a prior invocation. Use hosted mode to exercise closing a real session’s observed allocation. The shared flags above apply. unwind accepts neither --amount nor --setting.

​
Settings

Both entrypoints receive circuit.toml setting defaults. Only run accepts per-invocation overrides:
Resolution is circuit.toml default → --setting override. Unknown keys fail; values must match their types, booleans accept only true/false, single_select values must match defined options, and addresses must match the wallet VM family. Overrides do not persist: circuit.toml owns setting defaults, while .env owns persistent environment values. unwind always uses defaults.

​
Validate Agent Project

circuit check validates without authentication or Circuit API calls; dependency installation can contact the package registry. Use --path <path> to choose the project and --json for one result document. Invalid projects exit nonzero. It checks:
  • One root circuit.toml, valid fields, settings definitions, and [startingAsset].
  • Required index.ts, package.json, tsconfig.json, and bun.lock.
  • A top-level run export in a production-form build.
  • The description contract: a present, edited DESCRIPTION.md needs ## Summary, ## What it is, ## How it works, ## Strategy, and ## Risks. The What it is rows must match the category labels; errors identify missing sections or **Label:** rows. Missing descriptions and untouched starter templates pass.
Before validation, check replaces circuit-sdk.d.ts from the CLI’s bundled SDK and installs dependencies with scripts disabled. It runs the project’s local tsc --noEmit, then validates the production-form build and export. It never executes agent code or invents allocation. Upload repeats the build from pinned source in Circuit’s production environment.

​
Global Flags

The CLI accepts long flags only, without single-character aliases. --path is available on project commands including new, pull, check, run, unwind, and upload; new and pull use it as the output directory.