Skip to main content
Install the onyx command first, then authenticate with browser or device login. For the Windows via WSL2 preview (Onyx 0.1.20+) and Linux setup requirements, see Windows via WSL2.

​
Install the CLI

Run the installer:
The installer puts onyx in ~/.local/bin by default. If your shell does not already include that directory on PATH, the installer offers to add it for you. Verify the command:
Official releases collect structured command outcomes from the first eligible command. Review or change the preference with onyx telemetry status, onyx telemetry enable, or onyx telemetry disable. See CLI analytics and privacy for the exact data contract and environment-level opt-out controls. The installer starts automatic login during setup (device authorization in WSL). Press Esc while it is waiting if you need to authenticate later or use a global API key instead. For non-interactive installs:
For explicit system-wide installs, choose a writable install directory:

​
Log In Later

On a desktop, the CLI opens WorkOS in your browser and completes Authorization Code with PKCE through a one-time loopback callback. In WSL, SSH or another headless shell, it automatically uses device authorization and prints a verification URL and user code. Force either mode with onyx login --browser or onyx login --device. If your account belongs to one team, Onyx selects it silently. With multiple teams, choose from the terminal prompt or pass --team <team-id-or-unique-name>. The resulting session refreshes silently; active sessions can last up to one year, with reauthentication after 90 days of inactivity.
Profiles are team-scoped. If you belong to more than one team, run onyx profile list to see which profile is active.

​
Profile Basics

Profile names are derived from the first word of the team name. Onyx reuses an existing profile when the team and API URL already match. Logout revokes the remote CLI session and removes its local credential. Each login is bound to a one-time attempt issued by Onyx, so a revoked device cannot sign itself back in with a stored token; run onyx login again to create a new session. Headless device logins are completed through Onyx, which starts the device authorization and finishes the token exchange while you approve in a browser; tokens are handed to the CLI once and never stored by Onyx. When you point the CLI at a custom --api-url (anything other than production or localhost), it prints the API URL, OAuth issuer, and client ID and asks for confirmation; pass --trust-api-url in non-interactive shells. Upgrading from an older CLI: the first successful onyx login migrates your config to the current format and writes a sanitized backup next to it (team names and worker defaults only, no keys or tokens). A cancelled or failed login leaves the old config exactly as it was. Until then, other commands explain the migration instead of reporting a missing profile.

​
Automation and CI

Interactive login never creates or stores an API key. For scripts or CI, create a manual key in Settings → API Keys and use explicit environment overrides:

​
Local Development Against Another API

Only use this when developing Onyx itself. --local is shorthand for --api-url http://localhost:3000:
This stores a separate OAuth session profile for the local app; switch between it and the hosted app with onyx profile use <name>. onyx status prints the active profile and API target.

​
Developer Mode

When developing the Onyx agent package, keep the installed onyx command in place and switch it to a source checkout:
Developer mode runs the linked source CLI through Bun and links the managed Claude Code and Codex skill files to the checkout. Switch back to the installed release with:
Active agent sessions may need to reload or restart if they cache skill files. Developer mode changes which CLI source runs, not which app the CLI targets. To log experiments to a locally running app instead of the hosted one, use onyx login --local as described above.

​
Next Step

Quickstart

Link a repository and start auto research with /onyx.