Commands
Global Flags
Available on all commands:
The CLI is long-flag only - there are no single-character aliases (not even
-h/-v).
--path (agent project directory, default: current dir) is on the project commands - new, pull, check, run, unwind, upload. --var KEY=VALUE (inject an environment variable into the agent, repeatable) is on upload, run, unwind.
Project flags
Execution flags
Both commands print transaction diagnostics such as
tx confirmed [ethereum:8453]: <explorer-url> or tx failed [ethereum:8453]: <error>. With --json, these are output envelopes in the NDJSON stream.
circuit auth token
Default prints nothing but the bare bearer token (the passkey-signed wire string),
so TOKEN=$(circuit auth token) captures it for CI/CD. --json wraps the same
value as { "token": "..." }. --decode prints the decoded pre-b64 permit
(payload + WebAuthn proof) instead - a local decode, not a verification.
circuit auth whoami shows identity + what the token grants, but never the raw token itself.
circuit kraken
circuit kraken connect seals a Kraken API credential to your Circuit account.
It prompts for Credential label, Kraken API key, and Kraken private key;
for headless use, set KRAKEN_CREDENTIAL_LABEL, KRAKEN_API_KEY, and
KRAKEN_API_SECRET. Circuit authenticates the candidate with Kraken and derives
its read or trade access from Kraken’s response; the command does not accept
a claimed access level. For read access, enable Kraken’s Funds → Query, Orders and trades → Query
open orders & trades, Orders and trades → Query closed orders & trades,
and Data → Query ledger entries permissions. Trading also requires Orders
and trades → Create & modify orders and Orders and trades → Cancel & close
orders. Circuit checks only that the required permissions are present;
additional permissions do not block the credential or expand the operations
Circuit exposes. A key with only part of the trading set is admitted with
read access.
circuit kraken list prints id, label, and verified access. Use the
id as the credential to select when starting an agent that declares
[exchangeCredentials.kraken]; agents that declare trade = true also require an exact
minimumAllocation = { asset = "USD" | "USDC", amount = "..." } in circuit.toml and
--kraken-allocation <amount> at start. The flag is a quantity of the declared quote token.
The runtime exposes the selected
credential only to Circuit’s signing boundary; agent code cannot select or inspect it.
Reviewed operations and Terminal
Operations owns the intent shapes, approval rules, deadlines, and Terminal agent actions.operations create --file <path|-> mints an inert review UUID; --approve immediately approves it under the thirty-second lifecycle deadline. Creation alone never moves funds. Supported intents include swaps, sends, perps, spot, prediction buy/sell/redeem, and raw transactions.
File Exclusion (Upload)
Automatically excluded from uploads:*.md and *.sh files are uploaded as source; DESCRIPTION.md is read from the upload.
Additional patterns via filesToExclude in circuit.toml.
TypeScript uploads require an up-to-date bun.lock.
Environment and authentication
run, unwind, and upload load project .env with repeatable --var overrides taking precedence. Local execution injects these into the agent subprocess; uploads encrypt them at rest and decrypt at deployment. Read with process.env.KEY. The total limit is 4 KB including system variables; re-upload to rotate.
circuit auth login stores a passkey-signed permit in ~/.circuit/auth.toml, with separate [production], [staging], and [local] sections. Select with --env or CIRCUIT_ENV. The permit’s wallet.sign capability covers signing and private reads on owned hosted wallets or connected credentials; no separate execution token is needed.
For CI, set CIRCUIT_TOKEN to the output of circuit auth token; it takes precedence over the config file and bypasses browser login. Verify identity with circuit auth whoami, then invoke hosted commands normally. See authentication for login and token details.
RPC URLs (embedded mode)
Embedded runs use the local engine’s chain adapters and public RPC endpoints by default. Override them when you need a private provider, deterministic endpoint, or local fork. Persistent overrides live in~/.circuit/rpc.toml:
ethereum:<chainId> for EVM, bare solana for Solana. Per-call override via --rpc <networkId>=<url> (repeatable).