Overlord AI

Install

# Install the CLI globally via npm
npm install -g --no-fund overlord-cli

The published package is client-only: it ships command parsing, config and auth onboarding, connector setup, an HTTP backend client, and the local runner/launcher. It does not bundle a database — persistence lives behind the backend you point it at (the desktop/local backend or a hosted one).

First run

Run the guided setup to point the CLI at a backend, log in, install connectors, and choose the terminal used for launched agents:

ovld setup

Then confirm the connection:

ovld doctor       # verify backend reachability, connectors, and credentials
ovld config list  # show the resolved backend target

Authentication

# Configure the backend (interactive if unset), then log in with email/password
ovld auth login

# Log in with a long-lived USER_TOKEN (headless / CI)
ovld auth login --token out_xxxxxxxxxxxxxxxxxxxx

# Show backend URL and login status
ovld auth status

Account creation happens in the desktop app. In headless environments, set OVERLORD_USER_TOKEN (or OVLD_USER_TOKEN / USER_TOKEN) instead of logging in interactively — it is read directly and takes precedence over stored credentials. Mint tokens with ovld user-token create --label ci --expires-in 90d.

Point the CLI at a backend

Configuration lives in overlord.toml (per-instance, uncommitted; generate it with ovld init).

# Local backend (defaults to http://127.0.0.1:4310)
ovld config set local
ovld config set local http://127.0.0.1:4310

# Hosted backend
ovld config set cloud https://overlord.example.com

Install agent connectors

Connectors let a coding agent speak the Overlord protocol and receive mission context in its native harness.

# List installable connectors
ovld agent-setup

# Install or repair one connector (claude, codex, or cursor)
ovld agent-setup claude

# Install every supported connector at once
ovld agent-setup all

Common options: --dry-run to preview, --home <dir> to target a specific OVLD_HOME, and --json for machine-readable output. Re-run ovld agent-setup <agent> after an update to keep the connector in sync.

Create and launch missions

# Create a draft mission (prints a mission id like 1:1042)
ovld create "Add a user-facing error when the upload fails"

# Create a multi-objective mission
ovld create "Refactor the auth middleware" \
  --objectives-json '[
    {"objective": "Draft a plan for the refactor"},
    {"objective": "Implement the refactor per the plan"}
  ]'

# List missions
ovld missions list --status next-up,execute

# Launch an agent on a mission locally (opens a terminal with context pre-loaded)
ovld launch claude --mission-id 1:1042

# Queue an agent without spawning it here (a runner claims and launches it)
ovld prompt "Investigate the memory leak" --agent codex

Launch flags include --model, --thinking, --working-directory, --branch, --no-worktree, --pre-command, --terminal, and a repeatable --flag passthrough. If no project resolves from the current directory, register it first with ovld add-cwd or pass --project-id.

Terminal runner

When the web or desktop app enqueues an execution request (Run or auto-advance), a local runner claims the row and launches the agent for you. The backend never opens terminals itself.

# Poll continuously and launch queued requests (polls every 3s by default)
ovld runner start

# Claim and launch at most one queued request, then exit
ovld runner once

# Show this machine's runner identity and visible queue
ovld runner status

# Clear one active queue row by objective id
ovld runner clear <objective-uuid>

# Clear every active queue row visible to the runner
ovld runner clear-all

Common options: --poll-interval-ms, --project-id, --branch, --no-worktree.

See Agent Execution & Runner for architecture diagrams and the full request lifecycle.

Review delivered work

# Read the delivery summary for a mission
ovld mission deliveries 1:1042

# See every file change with its rationale
ovld changes rationales --mission-id 1:1042

# Full assembled mission context (history, shared state, artifacts)
ovld mission context 1:1042

When to use the CLI

Configuring the CLI and installing agent connectors on a new machine
Creating and launching missions from the terminal without the desktop app
Running ovld runner start so Run / auto-advance opens agents automatically
Reviewing deliveries and change rationales
Headless or CI environments where the desktop app is unavailable

Tips

Run ovld help or ovld <command> --help to see available options.
Use ovld doctor after upgrades to confirm connectors and the CLI are in sync.
ovld update upgrades the global overlord-cli install; ovld update --check only compares versions.
On a local backend, the desktop app and CLI share ~/.ovld/auth.json — log in once and both work.

CLI