> ## Documentation Index
> Fetch the complete documentation index at: https://onyxresearch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Commands supported by the onyx research workflow CLI.

The `onyx` command is the full terminal-only user and orchestrator CLI. The companion `onyx-worker` command exposes the worker-safe primitive surface used by supervised agents. In normal usage, you log in once and start research from an agent with `/onyx ...`; the agent composes these commands into the loop. Use this reference when debugging, scripting, or understanding what the agent is doing.

## Install and Version

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx --version
onyx-worker --version
```

## Developer Mode

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx developer status
onyx developer link [path]
onyx developer use dev [--skill-dir <path>] [--quiet]
onyx developer use release [--skill-dir <path>] [--quiet]
onyx developer sync-skill [--skill-dir <path>] [--quiet]
onyx developer unlink [--skill-dir <path>] [--quiet]
```

Developer mode lets contributors keep the persistent `onyx` command installed
while switching it between the release CLI and a linked source checkout.

## Login

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx login [--api-url <url>] [--local] [--print-url] [--refresh] [--port <port>] [--timeout <ms>]
```

Opens the browser login handoff, lets you choose a team, and stores or selects a local profile.

## Agent Skill

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx agent skill-path
onyx agent install-skill [--dir <path>] [--quiet]
```

`skill-path` prints the bundled skill location. `install-skill` copies it into
the managed Claude Code, Codex, and OpenCode skill directories by default:
`~/.claude/skills/onyx/SKILL.md`, `~/.agents/skills/onyx/SKILL.md`,
`${CODEX_HOME:-~/.codex}/skills/onyx/SKILL.md`, and
`~/.config/opencode/skills/onyx/SKILL.md`. Pass `--dir` only when you need to
install one custom skill root instead.

## Profiles

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx profile list
onyx profile use <name>
onyx profile delete <name>
onyx profile set-api-key-env <name> <ENV_VAR>
onyx profile worker get [profile]
onyx profile worker set [profile] --agent codex|claude|opencode [--model <model>]
onyx profile worker clear [profile] (--all | --agent | --model codex|claude|opencode)
```

Profiles are team-scoped. They can store a local key or read it from an
environment variable, and `onyx profile list` shows each profile's worker
defaults. Profiles can also store default worker agent/model choices used by
`onyx research run`, `onyx research start`, and `onyx worker run`. Deleting the
active profile clears the selected profile.

## Worker CLI

`onyx-worker` is the explicit worker-safe command surface. It includes only
primitives such as `research brief`, `research should-stop`, `exp run`,
`exp log`, `exp list`, `workflow status`, `tools run`, `knowledge add`,
and `summary upsert`. It excludes login/profile/developer, campaign/setup,
research orchestration, worker launching, public push, and removed research sync
commands.

Humans and orchestrators can run `onyx-worker` directly for local debugging. A
supervised worker receives an isolated `ONYX_HOME`, an `ONYX_WORKER_CONTEXT`
file, isolated temp directories, and a wrapper named `onyx-worker`. In that
runtime, `onyx-worker` binds commands to the assigned campaign, session,
hypothesis, and worker and rejects conflicting identity or target overrides.
The full `onyx` CLI refuses operational commands when worker context is present
and points back to `onyx-worker`.

## Campaigns

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx campaign setup \
  --name <name> \
  [--description <text>] \
  [--project-path <path>]
```

Creates or resumes a logical campaign by reading campaign metadata from
`onyx/setup.json`, resolving the repository remote from `origin`, and writing
remote campaign state through `/api/v1`. When GitHub access is available, Onyx
creates or reuses the internal project automatically. The Onyx orchestrator
usually runs this for you after interpreting your `/onyx` prompt.

The campaign records the current git HEAD as its base commit. It does not create
a shared research-history branch. The `onyx/` setup surface must be committed
before this command runs so worker worktrees inherit `setup.json`,
`validation.json`, `onyx.md`, and declared workflow tools.

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx campaign use <name> [--project-path <path>]
onyx campaign status [--project-path <path>]
```

`use` selects an existing remote campaign for direct one-agent mode and updates
the small local state cache. `status` prints the active campaign and cached
profile/project pointers.

## Setup and Tools

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx setup init [--goal <text>] [--metric-name <name>] [--metric-direction maximize|minimize] [--metric-unit <unit>] [--editable-scope <csv>] [--eval-command <cmd>] [--project-path <path>]
onyx setup validate [--project-path <path>]
onyx-worker tools run <tool-id> [args...] [--project-path <path>] [--timeout <seconds>]
```

`onyx setup init` creates `onyx/setup.json`, `onyx/validation.json`,
`onyx/onyx.md`, and `onyx/tools/evaluation/run.sh`. The scaffold is minimal and
does not infer editable scope, source files, or evaluation behavior from the
repository. `--editable-scope` and `--eval-command` write exactly the values you
provide. Without `--eval-command`, the scaffolded evaluation tool exits nonzero
until the orchestrator replaces it with a real eval that emits exactly one
primary metric line such as `METRIC score=0.42`.

`onyx setup validate` runs static local checks and writes
`onyx/validation.json`. It checks schema shape, setup hash, project path,
workflow/tool/resource references, a leading agent step, one required metric
step, referenced tool files, protected setup paths, and nontrivial narrative
context. Warnings for missing safety/readiness/reliability-style steps do not
block Research.

`onyx-worker tools run` executes a declared tool from `onyx/setup.json` with declared
cwd/env, timeouts, output capture, and local resource slot leases. It is for
manual diagnostics only: it never creates workflow state and never creates a
measured attempt. Operators can also reach this primitive through the full
`onyx` CLI.

## Experiments

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx-worker exp run --campaign <name> [--base <sha>] [--auto|--next] [--timeout <seconds>] [--checks-timeout <seconds>] [--project-path <path>]
onyx-worker exp run --resume [workflowRunId] [--auto|--next] [--project-path <path>]
onyx-worker workflow status [--run <workflowRunId>] [--campaign <name>] [--active] [--blocked] [--json]
```

`onyx-worker exp run` owns one workflow run: one experiment attempt, one result commit,
and one primary metric. In worker context, a new run can infer the clean current
`HEAD` as the base, pause at the leading agent step, and later resume with
`onyx-worker exp run --resume --auto` without copying workflow IDs. Command steps
execute declared setup tools, capture step logs under
`.git/onyx/workflow-runs/<workflowRunId>/`, and create terminal local attempt files
for `succeeded`, `failed`, `checks_failed`, or `setup_violation` outcomes.

`onyx-worker workflow status` is read-only. It shows the run status, next step, block
reason, step summaries, metric snapshot, run ref, result commit, and log paths.
With `--campaign`, it defaults to the latest workflow run for that campaign,
including terminal runs after completion. Add `--active` to restrict the lookup
to `running` or `paused` runs, or `--blocked` for blocked runs. In worker
context, status lookups are scoped to the current worker. `--run` remains an
exact lookup.

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx-worker exp log \
  [--campaign <name>] \
  [--run-ref <runRef>] \
  [--name <name>] \
  [--description <text>] \
  [--agent-notes <json-or-text>] \
  [--commit <sha>] \
  [--metric <value>] \
  [--metric-name <name>] \
  [--status succeeded|failed|checks_failed|setup_violation|running|queued] \
  [--allow-unmeasured] \
  [--project-path <path>]
```

Pushes the immutable git result ref first, then reports the measured experiment
directly to `/api/v1/research/campaigns/{id}/experiments`. The API returns
`recorded` or `duplicate`; server settlement later assigns accepted/discarded
disposition and any accepted index. Failed unmeasured attempts require
`--status failed --allow-unmeasured`. Protected path or out-of-scope diffs are
reported as `setup_violation`.

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx-worker exp list [--campaign <name>] [--status <status>] [--grep <regex>] [--limit <n>] [--json]
```

Reads paginated experiment state from the Onyx API. Online API access is
required.

## Research Sessions

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx research run --campaign <name> [--session <id>] [--workers <n>] [--max-concurrency <n>] [--launch-batch-size <n>] [--launch-interval-seconds <n>] [--provider-backoff-seconds <n>] [--heartbeat-sample-interval <seconds>] [--agent codex|claude|opencode] [--model <model>] [--worker-command "<cmd>"] [--hypotheses <json-array>] [--experiments <n>] [--max-minutes <n>] [--presence-interval <seconds>] [--foreground] [--json]
onyx research start --campaign <name> [--workers <n>] [--agent codex|claude|opencode] [--model <model>] [--hypotheses <json-array>] (--experiments <n> | --max-minutes <n>)
onyx research hypotheses --example
onyx research hypothesis add --session <id> (--plan <json-file> | --focus <text> --hypothesis <text>) [--name <name>] [--base <sha>] [--agent codex|claude|opencode]
onyx worker run --session <id> [--hypothesis <id>] [--agent codex|claude|opencode] [--model <model>] [--worker-command "<cmd>"] [--max-minutes <n>] [--worker-timeout <seconds>] [--startup-timeout <seconds>] [--stop-grace-seconds <seconds>] [--quiet]
onyx-worker research session-state-brief [--json]
onyx research stop [--session <id>] [--reason <text>]
onyx research finish [--campaign <name>] [--session <id>]
onyx research status [--campaign <name>] [--all-sessions] [--json] [--reconcile]
onyx-worker research brief [--campaign <name>] [--session <id>] [--hypothesis <id>] [--json]
```

`onyx research run` is the normal local supervisor. It creates or attaches to a
remote session, keeps up to `--workers` active local workers under
`--max-concurrency`, ramp-launches workers in batches, requests server-owned
worker leases in idempotent batches, refreshes the local session-state brief,
sends telemetry-only presence plus batched heartbeat updates, handles stop
requests, and records recovery metadata in manifests when push or report steps
fail. New sessions require at least one completion condition: `--experiments` or
`--max-minutes`. `--experiments` is the exact accepted report target enforced by
server settlement; `--max-minutes` is a deadline and wins if it arrives before
the experiment target.

The server owns worker slots, hypothesis assignment, report settlement, accepted
experiment order, and best projections. Workers remain cheap: the supervisor
keeps launching while the server grants leases. `onyx-worker exp log` pushes the
immutable result ref then records or deduplicates the experiment through the API.
Late attempts may be preserved as discarded diagnostics and do not count toward
targets or rankings. `onyx research start`
and `onyx worker run` remain lower-level/debug primitives. Worker startup
records the worker id, lease token, hypothesis id, worktree, manifest path,
worker CLI path, worker context path, raw provider log path, and readable
activity log path. `research status --json` returns structured launch
suggestions for debugging and recovery. `onyx-worker research brief` fetches a
compact campaign/session brief from the API; it prints Markdown by default and
structured data with `--json`.

`--agent` selects the coding harness. `--model` selects the model for that
harness; OpenCode model values must use `provider/model`. For new sessions,
worker settings resolve from command-line flags, then `ONYX_WORKER_AGENT` or
`ONYX_WORKER_MODEL`, then the active profile's worker defaults, then Codex.
Existing sessions keep their recorded worker agent/model and reject conflicting
flags.

`onyx research stop` requests cooperative shutdown. Workers poll for that state;
the harness waits for `--stop-grace-seconds` and then terminates the provider if
needed before running finalization. `onyx research finish` reconciles the remote
session finalization state and prints remaining incomplete worker reporting or
local recovery metadata when present.