> ## Documentation Index
> Fetch the complete documentation index at: https://onyxresearch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Onyx CLI and connect it to your team.

Install the `onyx` command first, then authenticate with the browser login flow.

## Install the CLI

Run the installer:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
curl -fsSL https://onyxresearch.ai/install.sh | ONYX_INSTALL_NO_PROMPT=1 bash
```

For explicit system-wide installs, choose a writable install directory:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
curl -fsSL https://onyxresearch.ai/install.sh | ONYX_INSTALL_DIR=/usr/local/bin bash
```

## Log In Later

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx login
```

The CLI opens your browser, asks you to choose a team, and creates or selects a local profile for that team.

<Tip>
  Profiles are team-scoped. If you belong to more than one team, run `onyx profile list` to see which profile is active.
</Tip>

## Profile Basics

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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. `--local` is shorthand for
`--api-url http://localhost:3000`:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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.

## Developer Mode

When developing the Onyx agent package, keep the installed `onyx` command in
place and switch it to a source checkout:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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.

## Next Step

<Card title="Quickstart" icon="rocket" href="/docs/quickstart" horizontal>
  Link a repository and start auto research with `/onyx`.
</Card>