> ## 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. # CLI Quick Reference > All CLI commands, flags, and behavior at a glance. ### Commands | Command | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `circuit new` | Create new agent project ([details](./development#create-new-agent)) | | `circuit pull ` | Download an Agent Builder chat locally ([details](./development#pull-agent-builder-chat)) | | `circuit check` | Validate project offline ([details](./development#check-agent-project)) | | `circuit run` | Execute agent locally; `--hosted engine` to use the hosted engine ([details](./development#run-agent-locally)) | | `circuit unwind` | Unwind agent locally; `--hosted engine` to use the hosted engine ([details](./development#unwind-agent)) | | `circuit upload` | Upload to Circuit infrastructure; `--enable=true\|false` to set visibility while publishing ([details](./uploading#upload-agent)) | | `circuit agent list` | List the agents you've published, with each one's enabled state | | `circuit auth login` | Authenticate via browser ([details](./authentication#sign-in)) | | `circuit auth login --local` | Mint an offline local session for local signing - no browser/account ([details](./authentication#local-sign-in-offline)) | | `circuit auth logout` | Clear stored credentials ([details](./authentication#sign-out)) | | `circuit auth whoami` | Show current user ([details](./authentication#logged-in-user-info)) | | `circuit auth token` | Print your bearer token for CI capture ([details](./authentication#token)) | | `circuit kraken connect` | Connect a Kraken API credential for uploaded agents | | `circuit kraken list` | List connected Kraken credentials | | `circuit wallet list` | List wallets in the local vault ([details](./wallets#list-wallets)) | | `circuit wallet add` | Add a local wallet (imported or generated) ([details](./wallets#add-wallet)) | | `circuit wallet delete
` | Remove a wallet from the vault ([details](./wallets#delete-wallet)) | | `circuit wallet export
` | Decrypt and print a local key ([details](./wallets#export-wallet)) | ### Global Flags Available on all commands: | Flag | Description | | ------------- | ------------------------------------------------------------------------------------------------------------- | | `--json` | Machine-readable JSON: a single document for one-shot commands, a live NDJSON event stream for `run`/`unwind` | | `--env ` | Target deployment: `production` (default), `staging`, or `local`. Takes precedence over `CIRCUIT_ENV`. | | `--help` | Show command help | | `--version` | Show version | 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`. ### `circuit new` Flags | Flag | Values | Description | | ------------ | ---------------------------------------- | -------------------- | | `--language` | `typescript`, `python` | Skip language prompt | | `--name` | any string | Skip name prompt | | `--template` | `basic`, `yield`, `index`, `hyperliquid` | Skip template prompt | ### `circuit run` Flags | Flag | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--hosted engine` | Borrow Circuit's hosted stack while your code runs locally: route the SDK's primitive calls through the hosted engine (sessions, policy, KMS signing, funding). Omit for a fully local run. Does **not** upload - see `--upload`. | | `--upload` | Upload the agent and start it through the web app's shared headless operation. The CLI waits for that exact first run to finish, then stops/releases the session; an interrupted start resumes from its persisted identity. Mutually exclusive with `--hosted`. | | `--dry-run` | Journal every signing / fund-moving write instead of executing it; reads still hit live providers. No keystore, login, or funding needed. A journaled request is not treated as an observed balance or position. Cannot be combined with `--hosted` or `--upload`. | | `--wallet
` | Local keystore wallet address, or hosted wallet address with `--hosted engine` / `--upload` | | `--mode ` | `auto` or `manual` (default: first in `allowedExecutionModes`) | | `--amount ` | Initial token allocation in smallest unit (requires `--hosted engine` or `--upload`; active sessions use top-up) | | `--var KEY=VALUE` | Set an environment variable for the agent (repeatable) | | `--setting KEY=VALUE` | Override a `circuit.toml` setting (repeatable). Required for settings marked `required = true`. | | `--keystore ` | (Embedded mode) override the keystore vault file location | | `--rpc =` | (Embedded mode) override a network's RPC URL (repeatable) | ### `circuit unwind` Flags | Flag | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--hosted engine` | Borrow Circuit's hosted stack while your code runs locally: read open positions from a running hosted session and close them through Circuit's policy/signing path. Omit for a fully local run. | | `--upload` | Dispatch the unwind to Circuit's hosted sandbox runner and tail it to completion. Mutually exclusive with `--hosted`. | | `--dry-run` | Journal `unwind()`'s writes instead of executing them. It receives an empty allocation because the harness owns no virtual-allocation fact; use hosted engine mode to unwind real observed positions. Cannot be combined with `--hosted` or `--upload`. | | `--wallet
` | Local keystore wallet address, or hosted wallet address with `--hosted engine` / `--upload` | | `--var KEY=VALUE` | Set an environment variable for the agent (repeatable) | | `--keystore ` | (Embedded mode) override the keystore vault file location | | `--rpc =` | (Embedded mode) override a network's RPC URL (repeatable) | `unwind` always runs in `auto` mode, so it has no `--mode`, `--amount`, or `--setting`. `run` and `unwind` print one transaction diagnostic per attempt, for example `tx confirmed [ethereum:8453]: https://basescan.org/tx/0x...` or `tx failed [ethereum:8453]: `. Under `--json` these are `output` event envelopes in the NDJSON stream. ### `circuit check` Flags No command-specific flags - `--path` (project directory) and the global flags only. ### `circuit pull` Flags | Flag | Description | | --------------- | ---------------------------------------------------- | | `--path ` | Output directory path. Defaults to `./`. | Used by Agent Builder's **Continue locally** command: ```bash theme={null} curl -fsSL https://api.circuit.org/dev | bash -s -- ``` ### `circuit upload` Flags | Flag | Description | | ---------------------- | ----------------------------------------------------------------------- | | `--var KEY=VALUE` | Set an environment variable for the agent (repeatable) | | `--enable=true\|false` | Set the agent's visibility while publishing; omit to leave it unchanged | ### `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`. By default the credential is connected with `read` and `trade` permissions; add `--read-only` to connect without trade permission. `circuit kraken list` prints `id`, `label`, permissions, and status. Use the `id` as the credential to select when starting an agent that declares `[exchangeCredentials.kraken]`; agents that declare `trade = true` also require `minimumAllocationUsd` in `circuit.toml` and a Kraken allocation at start - the user-declared Kraken allocation target for that session. The runtime exposes the selected credential as `agent.credentials.kraken`. ### `circuit check` Output Validates offline (no auth, no network): * `circuit.toml` exists at the project root (exactly one) * Config structure (valid `circuit.toml` fields) * `DESCRIPTION.md` present (optional) * Project structure - TypeScript (`index.ts` + `package.json` + `bun.lock`) or Python (`main.py` + `pyproject.toml`) * Settings definitions * Starting asset (`[startingAsset]`) configured `circuit check` does not run a language type-checker or Python syntax check - your IDE / pre-commit hooks own that. It does provision the environment-provided SDK and install dependencies first, so editors resolve `circuit:sdk` / `circuit_sdk` again. ### File Exclusion (Upload) Automatically excluded from uploads: | Category | Patterns | | ---------------------- | ------------------------------------------------------------------------ | | Version control | `.git/**`, `.svn/**` | | Dependencies | `node_modules/**`, `dist/**`, `venv/**`, `__pycache__/**` | | Secrets | `*.key`, `*.pem` | | IDE | `.vscode/**`, `.idea/**`, `*.swp` | | Build artifacts | `coverage/**`, `.pytest_cache/**`, `.cache/**` | | Unsupported lock files | `package-lock.json`, `bun.lockb`, `yarn.lock`, `pnpm-lock.yaml` | | Other | `Dockerfile`, `docker-compose.yml`, `*.md`, `*.sh`, `*.log`, `.DS_Store` | Additional patterns via `filesToExclude` in `circuit.toml`. TypeScript uploads require an up-to-date `bun.lock`. ### Environment Variables * **Source**: `.env` in project root + `--var` CLI flags (flags take precedence) * **Supported commands**: `run`, `unwind`, `upload` * **Local execution** (`run`, `unwind`): Env vars are injected into the spawned agent process * **Upload**: Encrypted at rest, decrypted at deploy time * **Access**: `process.env.KEY` (TypeScript) / `os.getenv("KEY")` (Python) * **Limit**: 4 KB total (including system vars) * **Rotation**: Re-upload to update ### Auth Storage Credentials stored in `~/.circuit/auth.toml` after `circuit auth login`: a passkey-signed permit (`circuit_permit_.`) used as the API auth token. There is no separate wallet-execution token - the api resolves wallet-signing material server-side from the permit's `wallet.sign` capability. One file with a `[production]`, `[staging]`, or `[local]` section per environment - set `CIRCUIT_ENV` to switch which section the CLI reads. (Same single-file pattern as `~/.aws/credentials` or `gh hosts.yml`.) ### CI / headless auth Set `CIRCUIT_TOKEN` to an API auth token (a passkey-signed permit) to skip `circuit auth login` entirely. The CLI reads this env var before looking for a config file, matching the convention used by `GH_TOKEN`, `NPM_TOKEN`, etc. Hosted-runtime commands resolve wallet-signing material from the permit, so no separate wallet-execution token is needed. Capture the token from a logged-in machine: ```bash theme={null} TOKEN=$(circuit auth token) export CIRCUIT_TOKEN="$TOKEN" circuit auth whoami # confirms who you are circuit run --hosted engine --wallet
# runs without a saved config ``` ### RPC URLs (embedded mode) Embedded runs use the shared execution adapter's 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`: ```toml theme={null} [rpc] "ethereum:1" = "https://eth-mainnet.alchemyapi.io/v2/KEY" "ethereum:137" = "https://polygon-mainnet.alchemyapi.io/v2/KEY" "solana" = "https://devnet.helius-rpc.com/?api-key=..." ``` Network IDs follow the canonical wire format: `ethereum:` for EVM, bare `solana` for Solana. Per-call override via `--rpc =` (repeatable).