> ## 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. # Uploading > CLI commands for uploading agents to Circuit. ### Upload Agent Upload your agent to Circuit infrastructure. ```bash theme={null} circuit upload ``` **Flags:** * `--path `: Upload from a specific agent directory instead of the current directory. * `--var KEY=VALUE`: Override/add env vars for this upload (repeatable). **What happens:** 1. Validates your project and `circuit.toml` (including `startingAsset` and deployment-region rules). A root-level `DESCRIPTION.md` (the agent's prose plan, maintained by the agent builder) is optional; when present its content is sent as the agent's description metadata with the uploaded version 2. Collects project files based on exclusion patterns (`DESCRIPTION.proposed.md`, a pending builder proposal, is never uploaded) 3. Reads environment variables from `.env` in the agent root (if present) 4. Applies `--var KEY=VALUE` overrides (CLI flags take precedence) 5. Generates a content hash (SHA-256) of your project files and env vars 6. Uploads code to Circuit infrastructure 7. Encrypts env vars at rest and stores them separately from code artifacts 8. Polls upload status until complete 9. Returns agent ID, version, and a link to the agent page **Important:** Your agent's `name` in `circuit.toml` is its permanent identity. Changing the name after uploading will create a new, separate agent — version history, sessions, and all other state belong to the original name. See [Agent Identity](../getting-started/circuit-toml-reference#agent-identity) for details. **Requirements:** * Must be authenticated (`circuit auth login`) * Valid `circuit.toml` configuration * TypeScript projects must include `index.ts`, `package.json`, and `bun.lock` * Python projects must include `main.py` and `pyproject.toml` * Dependencies installed locally before uploading For TypeScript projects, run `bun install` before uploading so `bun.lock` is present and up to date. For Python projects, run `uv sync` after editing dependencies so local checks and lockfiles match your project. ### Disable and Enable Agent Take an uploaded agent down from the app without deleting it, then bring it back. Handy in a pipeline to pull an agent from circulation on demand. ```bash theme={null} circuit disable circuit enable ``` **Flags:** * `--path `: Target a specific agent directory instead of the current one. **What `disable` does:** * Hides the agent from the app — it drops out of the agent list, the popular/related sections, its detail page, and the leaderboard. You (the creator) and admins can still reach it; turn on the **Show disabled agents** account setting to keep it in your own agent list. * Pauses every running session of the agent, across all users. No funds are moved — pausing only halts trading, and each session owner can still **Stop** or **Unwind** their own session from its card. * Blocks new sessions, resumes, and manual runs while the agent is disabled. **What `enable` does:** * Clears the disabled state so the agent is discoverable again. Previously paused sessions are **not** auto-resumed — each owner resumes their own. Both target the agent named in your `circuit.toml` (like `upload`) and require authentication (`circuit auth login`). ### Version Approval and Visibility Newly uploaded agents are **private by default**. That means the agent is only visible to you until an admin changes its visibility to public. After uploading, your new version goes through an approval process before it becomes visible to other users. **What you see vs. what others see:** As the agent creator, you always see your **latest version** on the agent detail page regardless of its approval status. This lets you verify that the upload succeeded and review the version details. Other users only see the **latest approved version**. This means that if you upload v0.2.0 but it hasn't been approved yet, you'll see v0.2.0 on the detail page while everyone else still sees v0.1.0. You can start sessions on your unapproved version, but other users will start sessions on the latest approved version once the agent is public. **File exclusion:** The CLI automatically excludes these patterns from uploads: * Version control: `.git/**`, `.svn/**` * Dependencies: `node_modules/**`, `dist/**`, `venv/**`, `__pycache__/**` * Secrets: `*.key`, `*.pem` * IDE files: `.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 can be added via `filesToExclude` in your agent config. > **Note:** `DESCRIPTION.md` is not uploaded as a file — its content is sent as agent metadata during upload. **Settings:** If your `circuit.toml` includes settings (e.g. `[settings.risk_level]`), they are validated during upload and snapshotted with the deployed version. Users will see the settings when starting a session with your agent. Changing settings requires a new upload. See [Settings](../getting-started/circuit-toml-reference#settings-section) for configuration details. **Content deduplication:** Circuit calculates a content hash of your uploaded files on the server. Each `circuit upload` mints a new `versionNumber` (rendered as `v1`, `v2`, …); you don't manage a `version` field in `circuit.toml`. If the latest non-failed version already has the same content hash, the upload is idempotent — the existing version is returned without redeploying. Reverting to older code re-uploads that content as a new `versionNumber` so the agent flips back to it. ### Environment Variables `run`, `unwind`, and `upload` load environment variables from `.env` files and support `--var` overrides. For `run` and `unwind`, env vars are injected into the locally spawned agent process. For `upload`, they are encrypted and stored for deploy-time injection. **Source and precedence:** * Base source: `.env` in the project root * Overrides: `--var KEY=VALUE` * If the same key exists in both, the CLI flag value wins Example Argument usage: ```bash theme={null} circuit upload --var KEY="value" --var KEY2="value2" ``` **Security model:** * Env vars are encrypted before being stored in Circuit's infrastructure. * Plaintext .env values are not stored in the uploaded source bundle or visible in the source code viewer. * At deploy time, env vars are decrypted and injected into the agent's environment. * Your code reads them normally with `process.env` (TypeScript) or `os.getenv()` (Python). **Important limits and behavior:** * Environment variables have a **4 KB total limit** (including system vars). * Changing env vars changes the upload content hash, so a new version is created. * To rotate env vars, re-upload your agent.