Skip to main content
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

​
Developer Mode

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

​
Login

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

​
Agent Skill

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

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

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

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

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.
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.
Reads paginated experiment state from the Onyx API. Online API access is required.

​
Research Sessions

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.