CLI

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.

macOS
Linux
Windows

python3 -m venv .venv
source .venv/bin/activate
pip install overmind
overmind --help

As a standalone tool, outside any project:

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.

python3 -m venv .venv
source .venv/bin/activate
pip install overmind
overmind --help

As a standalone tool, outside any project:

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.

Install into a virtual environment. It puts overmind on PATH while it is active:

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:

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.

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

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.

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`

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.

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`

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`

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.

`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`

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.

`overmind optimise`

overmind optimise start -c <capability> -d <dataset-id> && overmind optimise next

The client side of an optimisation run. 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`

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.

`overmind skills`

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.

Overview

Tracing

Core

Agent Testing

Model training

Agents & CLI

Platform

Install

First run

`overmind init`

`overmind sync`

`overmind chassis`

`overmind dataset`

`dataset upload FILE`

`dataset export DATASET`

`overmind connector`

`overmind optimise`

`optimise start`

The loop

`overmind model`

`overmind skills`

JSON output

​Install

​First run

​overmind init

​overmind sync

​overmind chassis

​overmind dataset

​dataset upload FILE

​dataset export DATASET

​overmind connector

​overmind optimise

​optimise start

​The loop

​overmind model

​overmind skills

​JSON output

Install

First run

`overmind init`

`overmind sync`

`overmind chassis`

`overmind dataset`

`dataset upload FILE`

`dataset export DATASET`

`overmind connector`

`overmind optimise`

`optimise start`

The loop

`overmind model`

`overmind skills`

JSON output