CLI reference

Install the CLI with npm install -g --no-fund overlord-cli. Run ovld help for the short command summary and ovld protocol help for the agent lifecycle reference. Management commands support --json where noted; protocol commands return JSON by default.

Setup, configuration, and diagnostics

Command	What it does
ovld help	Show the top-level help.
ovld version [--json]	Show the installed version.
ovld update [--check] [--force] [--json]	Check for or install the latest published CLI.
ovld init [--json]	Create overlord.toml for a local backend.
ovld serve [--host <h>] [--port <p>] [--db <path>] [--json]	Start the local web and REST server.
ovld doctor [--json]	Check the backend, connectors, agent binaries, and credentials.
ovld prune [--force] [--json]	Delete temporary contents under .overlord/tmp (keeps live session scratch unless --force).
ovld setup [--json]	Interactive first-run setup for backend, agents, and terminal.
ovld contract check <manifest-path> [--json]	Validate a component conformance manifest. This is for component maintainers.

Backend configuration

Command	What it does
ovld config list [--json]	Show resolved local configuration.
ovld config get <key> [--json]	Read backend, backend_mode, backend_url, web_host, web_port, or default_agent.
ovld config set [--json]	Choose a local or cloud backend interactively.
ovld config set local [url] [--json]	Use a local backend; default is http://127.0.0.1:4310.
ovld config set cloud <url> [--json]	Use a hosted backend.

Authentication and user tokens

Command	What it does
ovld auth login [--token <out_...>] [--json]	Configure the backend if necessary and sign in.
ovld auth status [--json]	Show the current backend URL and login state.
ovld user-token create --label <label> [--expires-in 90d] [--no-expiry] [--scope full|mission-lifecycle]	Create a token; its secret is shown only once.
ovld user-token list [--json]	List tokens without showing their secrets.
ovld user-token revoke <id> [--json]	Revoke a token immediately.
ovld user-token rename <id> <label> [--json]	Rename a token without rotating it.

Agents and organizations

Command	What it does
ovld agent-setup [--json]	List installable connectors.
ovld agent-setup <agent> [--dry-run] [--home <path>] [--json]	Install or repair one agent connector.
ovld agent-setup all [--dry-run] [--home <path>] [--json]	Install or repair all supported connectors.
ovld org-setup --org-name <name> [--workspace-name <name>] [--workspace-slug <slug>] [--logo <path>] [--no-input] [--if-needed] [--json]	Create an organization and its first workspace when the signed-in profile has none.

Supported built-in connector names currently include claude, codex, cursor, pi, antigravity, and opencode.

Projects and resources

Command	What it does
ovld create-project --name <name> [--directory <path>|--no-directory] [--json]	Create a project and optionally link a local directory.
ovld add-cwd [--directory <path>] [--project-id <id>] [--key <resource-key>] [--primary true|false] [--access read|read_write] [--json]	Link a local checkout.
ovld add-url --url <git-url> --project-id <id> [--key <resource-key>] [--primary true|false] [--access read|read_write]	Add or update a remote Git source.
ovld add-et --name <name> [--workspace-id <id-or-name>] [--json]	Announce this machine as an execution target (provisions or renames its local target).

Missions and launches

Command	What it does
ovld create "<objective>" [--objectives-json <json>] [--title <text>] [--project-id <id>] [--resource <key>] [--auto-advance|--no-auto-advance] [--json]	Create a draft mission.
ovld inbox create --title <text> --objective <text> [--json]	Create a private, account-owned unassigned task capture.
ovld prompt "<objective>" [--objectives-json <json>] [--title <text>] [--project-id <id>] [--resource <key>] [--agent <id>] [--auto-advance|--no-auto-advance] [--json]	Create a mission and queue execution.
ovld attach <mission-id> [agent] [--objective-id <id>] [--model <id>] [--thinking <level>] [--json]	Queue an agent for an existing mission.
ovld execution --mission-id <id> [--objective-id <id>] [--agent <id>] [--model <id>] [--thinking <level>] [--json]	Alias of attach without positional-missionId support. --mission-id is optional when --objective-id is a display id (e.g. coo:8.k7xm), same as attach.
ovld missions list [--status <csv>] [--query <text>] [--project-id <id>] [--limit <n>] [--json]	List missions.
ovld statuses list --project-id <id> [--json]	List one project’s board columns. Status names are per project; status types are not.
ovld mission context|events|deliveries|artifacts|rationales <mission-id> [--json]	Inspect a mission and its work record. Accepts an objective display id, which names its mission.
ovld launch <agent> --mission-id <id> [--objective-id <id>] [--working-directory <path>] [--model <id>] [--thinking <level>] [--branch <name>] [--no-worktree] [--terminal <launcher>|--no-terminal] [--pre-command <cmd>] [--dry-run] [--json]	Start an agent locally with mission context. --objective-id with a display id supplies --mission-id.
ovld restart <agent> ...	Resume an agent where native resume is supported.
ovld run|connect|resume <agent> <mission-id> ...	Compatibility aliases for local launch.

Use --terminal <launcher> to select Terminal, iTerm2, or a custom launcher, or --no-terminal to run the agent inline instead of spawning a terminal window. Repeat --flag <value> to pass supported options through to the agent, and use --pre-command <cmd> to run a shell command before the agent launches.

Runner and change history

Command	What it does
ovld runner once [--project-id <id>] [--branch <name>] [--no-worktree] [--terminal <launcher>|--no-terminal] [--dry-run] [--json]	Claim and launch at most one queued request.
ovld runner start [--project-id <id>] [--branch <name>] [--no-worktree] [--terminal <launcher>|--no-terminal] [--poll-interval-ms <n>] [--dry-run] [--json]	Run a foreground queue poller.
ovld runner status [--json]	Show runner identity and the visible queue.
ovld runner clear <objective-id> [--project-id <id>] [--json]	Clear one active request. The objective may be a UUID or a display id such as coo:8.k7xm.
ovld runner clear-all [--project-id <id>] [--json]	Clear all visible active requests.
ovld runner supervise [--json]	Run the adaptive persistent-runner loop.
ovld runner service install [--no-start] [--json]	Register the persistent runner service.
ovld runner service start|stop|restart [--json]	Control the registered service.
ovld runner service status [--json]	Show service state and diagnostics.
ovld runner service uninstall [--json]	Remove the registered service.
ovld changes status --mission-id <id> [--objective-id <id>] [--json]	Show changed-file status for a mission.
ovld changes rationales --mission-id <id> [--objective-id <id>] [--json]	List recorded file-change rationales.

Live sessions and decisions

These commands cover the agent-session surface — the live observe/decide/inject channel between a running agent harness and Overlord, separate from the durable mission protocol.

Command	What it does
ovld requests [--mission-id <id>] [--objective-id <id>] [--json]	List open and recent agent decisions, optionally restricted to one mission or objective.
ovld requests resolve <id> --revision <n> --decision allow|deny|ask [--text <text>]	Answer a held decision.
ovld inputs list --mission-id <id> [--objective-id <id>] [--json]	List session instructions and the effective channel for one mission or objective; an objective display id supplies the mission.
ovld inputs send --channel-id <id> --body <text> [--kind <kind>] [--json]	Send an instruction to one live session channel.
ovld agent-session capabilities [<agent>] [--json]	Print the fixture-backed capability descriptor for a harness — offline, authoritative.
ovld agent-session bind --agent <key> --native-session-id <id> [--mission-id <id>] [--objective-id <id>]	Correlate a harness-native session id with this process’s channel.
ovld agent-session event --agent <key> --payload-file -	Push one native harness event (connector-internal; silent, never blocks).
ovld agent-session request --agent <key> --payload-file -	Wait for a remote decision or defer to the harness (connector-internal).
ovld agent-session inbox --agent <key> --payload-file -	Claim one pending instruction and emit it natively (connector-internal).
ovld agent-session sidecar --agent <key> --port <port>	Drive a control-plane harness event stream, such as OpenCode (connector-internal).

agent-session event, request, inbox, and sidecar are the adapter runtime commands connectors invoke from hooks and extensions; capabilities and bind are the ones you would run directly while diagnosing a connector. See Agent-session adapters for per-harness behavior.

Agent protocol

The ovld protocol commands are primarily used by connectors and agent runtimes. They create the durable mission lifecycle that you see in Overlord. Every command below is available from ovld protocol help.

Command	Purpose
auth-status	Check backend and authentication readiness.
discover-project	Resolve a project from the working directory, project ID, or directory.
create-project	Create a project in one authorized workspace.
register-target	Register this machine as an execution target.
list-organizations	Return the current workspace context (the historic command name is retained).
attach	Start a full mission session and return its working context.
connect	Start a lightweight session without full context assembly.
load-context	Read mission context without starting a session.
list-deliveries	Read one mission’s normalized deliveries. An objective display id supplies the mission.
launch-objective	Queue a runner execution for one objective. Requires --objective-id (UUID or display id) and --agent.
reorder-future-objectives	Replace one mission’s complete future-objective order.
run-queue	Read live Run Queues; project scope can come from project, objective, or mission.
reorder-run-queue	Atomically replace every entry in one Run Queue.
queue-objective	Add or move one objective in the Run Queue. Requires --objective-id (UUID or display id).
dequeue-objective	Remove one objective from the Run Queue. Requires --objective-id.
retry-queue-entry	Retry one held Run Queue entry. Requires --objective-id or --entry.
create-run-queue	Create a paused queue definition. Requires project:update.
update-run-queue	Rename, pause, or resume a queue definition. Requires project:update.
delete-run-queue	Delete a queue, optionally moving its entries. Requires project:update.
reorder-project-run-queues	Replace the project’s complete queue-definition order. Requires project:update.
search (search-missions alias)	Find grouped mission, objective, and delivery matches by text, state, or project.
statuses	List one project’s board columns.
discuss-objective	Submit the latest draft objective for discussion without execution.
add-objectives	Append ordered objectives to a mission.
update-objective	Turn auto-advance on or off, or edit instruction text. Requires --objective-id.
delete-missions	Confirmed bulk soft-delete of one to 100 missions (requires --confirm).
delete-objectives	Confirmed bulk soft-delete of one to 100 objectives (requires --confirm).
create	Create a draft mission without attaching.
prompt	Create a mission and attach immediately.
record-work	Record completed chat work as a review mission.
update	Post progress, activity, and optional change rationale.
heartbeat	Send liveness information without creating a feed event.
ask	Raise a blocking question for a human reviewer.
deliver	Finish the session with summary, artifacts, and rationale.
resume-follow-up	Reopen completed work for a follow-up.
hook-event	Record a connector lifecycle event.
capture-change	Locally capture direct, objective-bound native edit paths (connector use).
sync-changes	Synchronize one bounded objective-ledger batch.
changes	Drain and report the exact objective ledger and hook health before delivery.
read-context / write-context	Read or store persistent mission context.
add-artifact	Create a mission artifact mid-turn without delivering.
update-artifact	Revise an existing mission artifact in place (label / content / URL).
attachment-list	List mission attachments.
attachment-download-url	Retrieve one attachment’s download URL.

Common protocol flags are --mission-id <id>, --objective-id <id>, --session-key <key>, --agent <identifier>, --model <identifier>, and --timeout <ms>. Most payload fields accept either inline JSON or a matching --*-file; use standard input (-) for larger payloads.

--objective-id is accepted anywhere --mission-id is, and takes an objective UUID or a display id such as coo:8.k7xm. A display id already names its mission, so --mission-id is optional whenever you pass one:

ovld protocol update --objective-id coo:8.k7xm --summary "Refactored the parser."
ovld protocol launch-objective --objective-id coo:8.k7xm --agent claude
ovld protocol queue-objective --objective-id coo:8.k7xm
ovld protocol list-deliveries --objective-id coo:8.k7xm

launch-objective, queue-objective, dequeue-objective, and update-objective require --objective-id as the primary argument — a display id is enough on its own. Use it when reconnecting to a mission that is running more than one objective — there, the mission id alone no longer identifies a unit of work. An objective UUID names no mission, so it still needs --mission-id beside it.

Run Queue entry operations (queue-objective, dequeue-objective, retry-queue-entry, and reorder-run-queue) require execution_request:create. Queue-definition operations (create-run-queue, update-run-queue, delete-run-queue, and reorder-project-run-queues) require project:update, so a mission-lifecycle-scoped token cannot perform them. run-queue accepts --project-id, --objective-id, or --mission-id, plus optional --queue. New queues start paused; resume one explicitly or directly launch a queued objective to start it.

Environment variables

Variable	Use
OVERLORD_USER_TOKEN, OVLD_USER_TOKEN, USER_TOKEN	Authentication token, checked in that order.
OVERLORD_BACKEND_URL, OVERLORD_BACKEND_URL_DEV	Backend URL fallback.
OVERLORD_EXECUTION_REQUEST_ID	Link an agent protocol attach to a runner request.
OVERLORD_OBJECTIVE_ID	Pin protocol attach to this objective display id (for example coo:8.k7xm).
OVERLORD_DEVICE_FINGERPRINT	Pin this process to a stable execution-target identity. Use when disposable containers (e.g. AgentPod) share one host environment and must not each register a new target from their ephemeral hostname.
OVERLORD_DEVICE_LABEL	Override the human-facing device name for this machine’s execution target. Optional; falls back to the hostname. Does not affect the fingerprint unless OVERLORD_DEVICE_FINGERPRINT is also set.
SESSION_KEY	Session-key fallback for protocol commands.
OVLD_HOME	Relocate the CLI’s credentials and configuration.
OVERLORD_WEB_HOST, OVERLORD_WEB_PORT, OVERLORD_SQLITE_PATH	Defaults for ovld serve.