---
title: "The CLI"
description: "The local o8 command line — an agent-first, JSON-by-default wrapper over o8's API, on $PATH in every worktree."
canonical_url: https://o8.run/docs/cli
md_url: https://o8.run/docs/cli.md
last_updated: 2026-06-25
version: "0.1.431"
stability: stable
---

# The CLI

> The local o8 command line — an agent-first, JSON-by-default wrapper over o8's API, on $PATH in every worktree.

The `o8` CLI is an **agent-first wrapper over o8's local API.** It's on `$PATH` inside every packet worktree, so a dispatched worker drives o8 with it instead of curling the API — and you can use it too, for terminal-native fleet control.

It's built for programs to consume: **JSON to stdout by default** (`--human` for pretty output), every payload carries a versioned schema, and the exit codes mean things — `0` ok, `2` connection refused, `3` unauthorized, `4` not found, `5` conflict — so an agent branches on the code without parsing strings. It's **loopback + token gated**: it works locally with no auth, and refuses over the network. It auto-resolves your packet and lane from the current directory.

## The command groups

| Group | What it's for |
|---|---|
| `o8 status` · `version` · `doctor` | Fleet snapshot, versions, and a health check (`doctor --reap` clears zombie lanes). |
| `o8 ask` | Ask the Brain a question; get a cited answer, scoped to your repo. |
| `o8 run` | Run a process in an o8-owned terminal you can watch live (`--detach` for servers). |
| `o8 packet` | Your dispatched work: `scope`, `diff`, `commit`, `review`, `report`, `capture` (visual proof). |
| `o8 spec` | Annotate the repo's o8.md — `read`, `pending`, `comment`, `suggest`, `resolve` (never overwrite). |
| `o8 task` | The project work queue: `list`, `create`, `claim`, `dispatch`, `report`. |
| `o8 lane` | `lane touches --path <file>` — which other live lanes touch a file. |
| `o8 cortex` | `cortex observe` — a worker writes a fact back to the Brain. |
| `o8 browser` | Drive a browser the operator can watch: `open`, `read`, `click`, `type`, `wait`. |
| `o8 team` | Coordinate multiple agents in one repo: `who`, `status`, `lease`. |

A few in practice:

- `o8 status` — the whole fleet at a glance.
- `o8 ask "which middleware gate covers new API routes?"`
- `o8 run -- pytest -q` — run tests in a watchable terminal.
- `o8 packet diff`, then `o8 packet review --approve`.

## Who uses it

- **Dispatched workers (primary).** A worker in its worktree gets its scope with `o8 packet scope`, commits with `o8 packet commit` (instead of raw git), consults the Brain with `o8 ask`, and surfaces progress with `o8 packet report` — all auto-scoped to its packet.
- **You (power user).** Terminal-native control: `o8 status` for the snapshot, `o8 run` to launch something you watch live, `o8 packet review --approve` to merge.

If `o8` isn't found, launch the o8 app once — it installs the CLI symlink on first run.