> ## Documentation Index
> Fetch the complete documentation index at: https://overmind-b84ae13c-codex-workshop-queue-capacity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The overmind command — init, sync, chassis, dataset upload and export, connectors, the optimise loop, model checkpoints, and skills.

The `overmind` command ships with the Python package. It is the local half of every workflow that touches your filesystem: it installs the workflow skills and MCP entry, syncs `overmind.toml` with the server, lands files as datasets, adds tracing connectors, drives optimisation runs in your working tree, and downloads weights. The MCP server never edits a repository or moves bytes; the CLI does. The package is MIT.

## Install

Install the CLI into a virtual environment, or as a standalone tool with `uv` or `pipx`. Both put `overmind` on `PATH`.

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    pip install overmind
    overmind --help
    ```

    As a standalone tool, outside any project:

    ```bash theme={null}
    uv tool install overmind          # or: pipx install overmind
    ```

    Homebrew's Python refuses a global `pip install` with `externally-managed-environment`. Use a virtual environment or a tool install.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    pip install overmind
    overmind --help
    ```

    As a standalone tool, outside any project:

    ```bash theme={null}
    uv tool install overmind          # or: pipx install overmind
    ```

    Debian and Ubuntu mark the system Python as externally managed, so a global `pip install` fails with `externally-managed-environment`. Use a virtual environment or a tool install.
  </Tab>

  <Tab title="Windows">
    Install into a virtual environment. It puts `overmind` on `PATH` while it is active:

    ```powershell theme={null}
    python -m venv .venv
    .venv\Scripts\Activate.ps1          # cmd.exe: .venv\Scripts\activate.bat
    pip install overmind
    overmind --help
    ```

    If PowerShell refuses to run `Activate.ps1`, allow local scripts for your user once:

    ```powershell theme={null}
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```

    A global `pip install` puts `overmind.exe` in the interpreter's `Scripts` folder, which is not on `PATH` by default. The command is then not found; `python -m overmind` runs the same CLI.
  </Tab>
</Tabs>

The base package is the CLI and the inference client. The `tracing` extra adds the tracing SDK and every provider instrumentor:

```bash theme={null}
pip install "overmind[tracing]"
```

When Overmind is a project dependency, run commands through that project's environment (`uv run overmind`, `poetry run overmind`, or its virtual-environment executable). An editable installation does not update skill copies already in a repository. Refresh the installed skill with `uv run overmind skills sync overmind --ide <cursor|claude|opencode|codex>` using the appropriate project runner, then start a new conversation so the coding agent reads it.

## First run

Every command that talks to the API resolves its key in the same order: `--api-key`, then the project credential in `.overmind/credentials.toml` (written by `overmind sync`), then `OVERMIND_API_KEY`. The base URL comes from `--api-url`, `OVERMIND_API_URL`, or `base-url` in `overmind.toml`; the hosted default is `https://api.overmindlab.ai`. Keys go over the wire as `X-Api-Key`. `overmind --version` prints the package version; `overmind <command> --help` prints flags.

```bash theme={null}
export OVERMIND_API_KEY=<your-api-key>    # PowerShell: $env:OVERMIND_API_KEY = "<your-api-key>"
export OVERMIND_API_URL=<your-api-url>    # self-hosted only, e.g. http://localhost:8000
overmind init --ide cursor        # or claude | opencode | codex
overmind sync                     # create the project, save the project key
```

Then in your coding agent, `/overmind setup` scans the repository, writes capabilities into `overmind.toml`, and runs `overmind sync` to push them. The installed skill recognises the repository and verified connection, previews the onboarding roadmap, and reports repository-specific findings alongside the current stage out of ten, completed stages, and stages still to follow. A pre-sync handoff names the destination, included data, credential checks performed, and configuration to review. The finish reports the synced result, outstanding verification, and one recommended next action without automatically starting it.

## `overmind init`

```bash theme={null}
overmind init --ide cursor            # cursor, claude, claude_code, opencode or codex
overmind init --ide claude --env local
```

| Option | Default | Meaning |
| - | - | - |
| `--ide` | required | `cursor`, `claude` (alias `claude_code`, `claude-code`), `opencode`, or `codex` |
| `--env` | `production` | `production`, `staging`, or `local` (`http://localhost:8000`) |
| `--api-url` | `$OVERMIND_API_URL` | Base URL; overrides `--env` for both the MCP entry and `overmind.toml` |

Installs the workflow skills under the client's directory (`.agents/skills/` for Cursor and Codex, `.claude/skills/`, `.opencode/skills/`), writes the `/overmind` slash commands (Cursor only: `.cursor/commands/`), adds the Overmind MCP entry to the client's own config, and seeds `overmind.toml` when it is missing. Other configured MCP servers are left untouched. An existing `overmind.toml` is left unchanged. For Cursor, Overmind skill copies left in `.cursor/skills/` by an earlier version are removed, so Cursor does not list them twice.

| Client | MCP config | Skill install |
| - | - | - |
| Cursor | `.cursor/mcp.json` | `.agents/skills` |
| Claude Code | `~/.claude.json`, local scope for this directory | `.claude/skills` |
| OpenCode | `opencode.json` | `.opencode/skills` |
| Codex | `.codex/config.toml` | `.agents/skills` |

The MCP entry is written with the saved project key when `.overmind/credentials.toml` already exists; otherwise it is written without a key and `overmind sync` fills it in. Claude Code's entry is a local-scope server in `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`), so it needs no `.mcp.json` approval and a committed `.mcp.json` is left untouched. Any repository file that receives a key is added to `.git/info/exclude` and set to mode `0600`; the CLI refuses to write a key into a tracked file. `init` does not persist the bootstrap account key.

Slash commands: `/overmind`, `/overmind onboard`, `/overmind setup`, `/overmind ensure-tracing`, `/overmind dataset`, `/overmind finetune`, `/overmind optimise`, `/overmind backtest`. Cursor gets a command file for each; Claude Code passes the word after `/overmind` to the skill, which opens the matching reference.

## `overmind sync`

Two-way sync of `overmind.toml` with `POST` / `GET /api/v1/sync`.

```bash theme={null}
overmind sync                      # up, then down
overmind sync up                   # POST the local snapshot; write ids back
overmind sync down                 # GET the server snapshot; overwrite the local file
```

| Option | Default | Meaning |
| - | - | - |
| `--api-key` | resolved | Overmind API key |
| `--api-url` | `$OVERMIND_API_URL` | Backend base URL |
| `--path` | `overmind.toml` | Path to the manifest |

`up` (and the default both-ways run) POSTs the local snapshot. On success it writes assigned capability ids back into `overmind.toml`. When `project-id` is missing and the key is **account-scoped**, it creates a project named after `project-name` in the toml (seeded at init from the repo directory), writes `project-id`, saves a project-scoped key to `.overmind/credentials.toml`, and rewrites every configured MCP entry with it. Reload the coding agent once after that. Project-scoped keys cannot create a project — set `project-id` first.

`down` requires `project-id` already in the toml. Leftover capabilities come back with `archived = true`.

Commit `overmind.toml`. Do not commit `.overmind/credentials.toml`.

## `overmind chassis`

```bash theme={null}
overmind chassis                   # print the AST digest for the current directory
overmind chassis --root PATH
```

Prints a deterministic inventory of Python functions and call edges under `--root` (default `.`). `/overmind setup` runs this before it authors capability cards; the digest is the ground truth those cards must not contradict. You rarely need to run it yourself.

Skipped directories: `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `.tox`, `site-packages`, `dist`, `build`.

## `overmind dataset`

```bash theme={null}
overmind dataset upload rows.jsonl --intent eval --wait --json
overmind dataset upload traffic.parquet --split 20 --split-position random
overmind dataset export <dataset-id> --format csv --cell <cell-id> --output triage.csv
```

### `dataset upload FILE`

| Option | Default | Meaning |
| - | - | - |
| `--project-id` | `project-id` in the toml | Project UUID |
| `--intent` | proposed at landing | `train` or `eval` |
| `--capability` | none | Capability UUID to align the dataset with |
| `--split` | off | Land a train dataset and an eval dataset; the eval share in percent (1–99). Drop `--intent`. |
| `--split-position` | `tail` | Where the eval rows come from: `head`, `tail`, or `random` |
| `--wait` | off | Wait for the landing and the agent's first preparation; exit 1 with the dataset's error if either fails |
| `--api-key`, `--api-url`, `--path` | resolved | Credentials; `--path` points at `overmind.toml` |
| `--json` | off | Print one machine-readable object |

Reserves an upload at `POST /api/uploads/`, streams the file in resumable chunks with `PUT /api/uploads/{id}/chunk/` (the CLI reads the received offset back before each chunk), then creates the dataset with `POST /api/datasets/` and `source: {upload_id, filename}`. The file may be `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson` or `.parquet`, optionally gzipped. With `--split`, it posts to `/api/datasets/split/` instead and the JSON result carries `id` (train) and `eval_id`. The JSON result also carries `state` (`landing` until the landing run finishes) and `next_mcp_actions` — `get_job(kind="dataset_run")` then `inspect_dataset` — which is how the `/overmind dataset` command reads the outcome back. See [Datasets](/core/datasets#create-a-dataset).

### `dataset export DATASET`

| Option | Default | Meaning |
| - | - | - |
| `--format` | `jsonl` | `jsonl` or `csv` |
| `--cell` | active version | Cell UUID or a version such as `1.2` |
| `--output` | server filename | Local path; must not exist |
| `--api-key`, `--api-url`, `--path`, `--json` | | As above |

Streams `GET /api/datasets/{id}/export/?fmt=…[&cell=…]` to a new local file and refuses to overwrite. The export is a raw stream and never counts as a use of the dataset.

## `overmind connector`

```bash theme={null}
overmind connector add langfuse --json
overmind connector add langsmith
```

| Option | Default | Meaning |
| - | - | - |
| `--project-id` | `project-id` in the toml | Project UUID |
| `--name` | the connector type | Display name |
| `--base-url` | provider default | Provider API base URL (`LANGFUSE_HOST` for Langfuse) |
| `--api-key`, `--api-url`, `--path`, `--json` | resolved | Overmind credentials |

Creates a tracing connector from provider credentials. Types: `langfuse`, `langsmith`, `braintrust`, `galileo`. Provider keys come from the environment or a TTY prompt — never paste them into chat.

| Type | Env |
| - | - |
| Langfuse | `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` |
| LangSmith | `LANGSMITH_API_KEY` |
| Braintrust | `BRAINTRUST_API_KEY` |
| Galileo | `GALILEO_API_KEY` |

Generic fallback: `OVERMIND_CONNECTOR_API_KEY` and, for Langfuse, `OVERMIND_CONNECTOR_API_SECRET`. The JSON result carries the connector `id` and `next_mcp_calls` — `inspect_connectors`, `configure_connector`, `sync_connector`. Auto-sync starts off; configure the source project and capability mapping through MCP or the Console, then sync. See [Observability](/core/observability#getting-traces-in).

## `overmind optimise`

```bash theme={null}
overmind optimise start -c <capability> -d <dataset-id> && overmind optimise next
```

The client side of an [optimisation run](/agent-testing/optimisers). Every subcommand reads its key through the usual chain and its base URL from `OVERMIND_API_URL` or the toml. State lives in `.overmind/optimise_state.json`; the eval dataset is cached under `.overmind/datasets/`.

### `optimise start`

| Option | Default | Meaning |
| - | - | - |
| `--capability`, `-c` | | Capability slug from `overmind.toml` or UUID |
| `--dataset`, `-d` | | Dataset UUID |
| `--experiment`, `-e` | | Attach to an existing experiment instead of creating one |
| `--eval-set` | the capability's active set | Eval set UUID |
| `--mode` | `optimize` | `optimize` or `hybrid` |
| `--model`, `-m` | | OpenRouter model id; hybrid only, repeatable |
| `--iterations` | 5 | Max candidate iterations |
| `--candidates` | 3 | Candidates per iteration |

Pass `--capability` and `--dataset`, or `--experiment` to attach. Creates the experiment, caches the dataset, records it as the active experiment, and prints `Next: overmind optimise next`.

### The loop

Each verb takes `--experiment`/`-e` (default: the active experiment) and posts its outputs for the server to score.

| Subcommand | What it does |
| - | - |
| `next` | Print the next action for the coding agent |
| `set-template FILE` | Upload the shell command template the datapoint runner renders |
| `run-smoke` | Run the first datapoint once to verify the template; exit 1 on failure |
| `run-baseline` | Run the full dataset against the current tree, post outputs, wait for scores |
| `add-candidate --diff FILE` | Queue a unified diff for the next iteration |
| `run-iteration` | Apply queued diffs, run every datapoint, post outputs, wait for scores |
| `status [--json]` | Show experiment status and scores |
| `complete` | Seal the experiment and record the winner on the server |

## `overmind model`

```bash theme={null}
overmind model download-checkpoint <deployment-id> --output ./weights.zip
```

| Option | Default | Meaning |
| - | - | - |
| `--output` | the archive's own name | Local path; must not exist |
| `--api-key`, `--api-url`, `--path`, `--json` | | As above |

Calls `GET /api/deployed-models/{id}/checkpoints/`, which returns `{name, size_bytes, download_url}` for the archived checkpoint zip — a presigned link valid for one hour — and streams it to a new local file. The deployment id comes from the Console or the `overmind://deployments/{deployment}` resource. See [Inference](/models/inference).

## `overmind skills`

```bash theme={null}
overmind skills list --verbose
overmind skills sync overmind --ide cursor
```

`list` prints the installed and available agent skills. `sync NAME...` replaces one or more skills in the client directory chosen by `--ide` (default `cursor`), so files removed from a skill do not stay behind. `overmind init` runs `sync overmind` for you.

## JSON output

`--json` on `dataset upload`, `dataset export`, `connector add` and `model download-checkpoint` prints one machine-readable object and nothing else; on failure they print `{"error": "..."}` and exit 1. `optimise status --json` prints the experiment. This is how the `/overmind` commands hand a local step to the CLI and read the result back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.