Skip to main content
The onyx command is terminal-only and primitive-oriented. 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

onyx --version

​
Developer Mode

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. link detects either an onyx-agent checkout or an onyx-research checkout with packages/agent. use dev dispatches commands through Bun to the linked source CLI and symlinks the managed skill file to the checkout. use release restores the installed release CLI and release skill. Active agent sessions may need to reload or restart if they cache skill files.

​
Login

onyx login [--api-url <url>] [--print-url] [--refresh] [--port <port>] [--timeout <ms>]
Opens the browser login handoff, lets you choose a team, and stores or selects a local profile. Use --refresh to rotate the stored key for a selected team.

​
Agent Skill

onyx agent skill-path
onyx agent install-skill [--dir <path>] [--quiet]
skill-path prints the bundled skill location. install-skill copies it into the default Claude Code personal skill directory (~/.claude/skills/onyx/SKILL.md) or a provided path.

​
Profiles

onyx profile list
onyx profile use <name>
onyx profile delete <name>
onyx profile set-api-key-env <name> <ENV_VAR>
Profiles are team-scoped. They can store a local key or read it from an environment variable. Deleting the active profile clears the selected profile.

​
Branches

onyx branch create \
  --name <name> \
  --metric <name> \
  [--unit <unit>] \
  [--direction maximize|minimize] \
  [--description <text>] \
  [--project-path <path>]
Creates or checks out onyx/{name}, records branch metadata, infers the repository from origin, and queues the branch for sync. When GitHub access is available, the first successful sync creates or reuses the internal project automatically. The Onyx agent usually runs this for you after interpreting your /onyx prompt.

​
Experiments

onyx exp run [--branch <name>] [--timeout <seconds>] [--checks-timeout <seconds>] [--project-path <path>] [--no-log]
Runs onyx/eval.sh, parses METRIC lines, optionally runs onyx/checks.sh, and stores the latest run locally. The Onyx agent usually creates those scripts and invokes this command for each measured attempt. 
onyx exp log \
  [--branch <name>] \
  [--name <name>] \
  [--description <text>] \
  [--agent-notes <json-or-text>] \
  [--commit <sha>] \
  [--metric <value>] \
  [--metric-name <name>] \
  [--status succeeded|failed|checks_failed|accepted|rejected|running|queued] \
  [--project-path <path>]
Records a measured or manually supplied experiment and syncs when possible. 
onyx exp list [--branch <name>] [--status <status>] [--grep <regex>] [--limit <n>] [--json]
Searches the local history cache. Run onyx sync first after a fresh clone to hydrate history from the app.

​
Session and Sync

onyx listen
onyx status
onyx push
onyx sync [--project <id>] [--repository-url <url>] [--project-path <path>]
  • listen: live read-only view of local activity.
  • status: active branch, project path, pending outbox records, and project resolution.
  • push: pushes the current branch and flushes the outbox.
  • sync: flushes the outbox, lazily provisions the project if needed, hydrates history, and requests repository sync.

​
Environment

VariableMeaning
ONYX_API_KEYExplicit API key override.
ONYX_API_URLExplicit API URL override.
Profile env varA profile-specific secret configured by set-api-key-env.