Skip to main content
Install the onyx command first, then authenticate with the browser login flow.

​
Install the CLI

Run the installer: 
curl -fsSL https://onyxresearch.ai/install.sh | bash
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: 
onyx --version
The installer starts browser login during setup. Press Esc while it is waiting if you need to authenticate later or use a global API key instead. For non-interactive installs: 
curl -fsSL https://onyxresearch.ai/install.sh | ONYX_INSTALL_NO_PROMPT=1 bash
For explicit system-wide installs, choose a writable install directory: 
curl -fsSL https://onyxresearch.ai/install.sh | ONYX_INSTALL_DIR=/usr/local/bin bash

​
Log In Later

onyx login
The CLI opens your browser, asks you to choose a team, and creates or selects a local profile for that team.
Profiles are team-scoped. If you belong to more than one team, run onyx profile list to see which profile is active.

​
Profile Basics

onyx profile list
onyx profile use <name>
onyx profile delete <name>
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. Deleting a profile only removes the local credential entry; it does not delete the team or revoke the API key in the app.

​
Rotating or Supplying Keys Manually

For normal local work, prefer onyx login. For keys created in the app settings page, store the secret in an environment variable and point the profile at it: 
export ONYX_TEAM_API_KEY="onyx_..."
onyx profile set-api-key-env team ONYX_TEAM_API_KEY
For scripts or CI, you can also use explicit overrides: 
export ONYX_API_KEY="onyx_..."
export ONYX_API_URL="https://app.onyxresearch.ai"
onyx status

​
Local Development Against Another API

Only use this when developing Onyx itself: 
onyx login --api-url http://localhost:3000

​
Developer Mode

When developing the Onyx agent package, keep the installed onyx command in place and switch it to a source checkout: 
onyx developer link .
onyx developer use dev
Developer mode runs the linked source CLI through Bun and links the managed Claude Code skill at ~/.claude/skills/onyx/SKILL.md to the checkout. Switch back to the installed release with: 
onyx developer use release
Active agent sessions may need to reload or restart if they cache skill files.

​
Next Step

Quickstart

Link a repository and start auto research with /onyx.