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:
onyx profile listonyx 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.
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
Only use this when developing Onyx itself. --local is shorthand for
--api-url http://localhost:3000:
onyx login --local
This stores a separate 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.
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 and Codex skill files 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.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.
