# CLI

Interact with Quor from the command line

<img src="/assets/overview/cli/cli_hero.png" alt="Quor CLI terminal interface" />

The Quor CLI is a terminal interface for chatting with your Quor agents and querying your knowledge base.
Built with Go using [Bubble Tea](https://github.com/charmbracelet/bubbletea),
it provides both an interactive TUI and non-interactive commands for scripting and automation.

## Installation

### PyPI (recommended)

```shell
uv tool install onyx-cli
```

Or with pip:

```shell
pip install onyx-cli
```

{/* TODO: Replace with actual PyPI URL once published */}
<Card title="PyPI Package" icon="python" href="https://pypi.org/project/onyx-cli/">
  uv tool install onyx-cli
</Card>

### Build from Source

Requires [Go 1.26+](https://go.dev/dl/).

```shell
git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/cli
go build -o onyx-cli .
sudo mv onyx-cli /usr/local/bin/
```

## Setup

Run the interactive setup to configure your server URL and API key:

```shell
onyx-cli configure
```

This prompts for your Quor server URL and API key, tests the connection,
and saves config to `~/.config/onyx-cli/config.json`.

### Generating an Access Token

Navigate to **User Settings > Accounts & Access > New Access Token** (`/app/settings/accounts-access`)
to create an access token for the CLI.

<img src="/assets/overview/cli/access_tokens.png" alt="Accounts & Access page showing the Access Tokens section" width="600" />

<img src="/assets/overview/cli/create_access_token.png" alt="Create Access Token modal with token name and expiration options" width="500" />

### Environment Variables

Environment variables override config file values. This is useful for CI/CD pipelines and scripting.

| Variable | Required | Description |
|----------|----------|-------------|
| `ONYX_SERVER_URL` | No | Server base URL (default: `https://cloud.quor.app`) |
| `ONYX_API_KEY` | Yes | API key for authentication |
| `ONYX_PERSONA_ID` | No | Default agent/persona ID |

### Validate Configuration

Verify that your configuration is correct and the server is reachable:

```shell
onyx-cli validate-config
```

## Commands

| Command | Description |
|---------|-------------|
| `onyx-cli` | Launch the interactive chat TUI (default) |
| `onyx-cli ask` | Ask a one-shot question (non-interactive) |
| `onyx-cli agents` | List available agents |
| `onyx-cli configure` | Configure server URL and API key |
| `onyx-cli validate-config` | Validate configuration and test connection |
| `onyx-cli deploy` | Install and manage a self-hosted Quor deployment |

### Interactive Chat

```shell
onyx-cli
```

Opens a full-screen terminal UI for conversational interaction with your Quor agents.

### One-Shot Questions

Ask a question and get a response without entering the TUI:

```shell
onyx-cli ask "What is our company's PTO policy?"
```

Use `--agent-id` to target a specific agent:

```shell
onyx-cli ask --agent-id 5 "Summarize our Q4 roadmap"
```

Use `--json` for structured NDJSON output (useful for scripting):

```shell
onyx-cli ask --json "List all active API integrations"
```

| Flag | Description |
|------|-------------|
| `--agent-id <int>` | Agent ID to use (overrides default) |
| `--json` | Output NDJSON events instead of plain text |

### List Agents

```shell
onyx-cli agents
onyx-cli agents --json
```

Prints a table of available agent IDs, names, and descriptions.

### Self-Hosted Deployment

The `deploy` command group installs and manages a self-hosted Docker Compose deployment of Quor — a guided installer
plus `upgrade`, `status`, `logs`, `stop`, and `uninstall` commands:

```shell
onyx-cli deploy install
```

<Card title="Deploy with the Quor CLI" icon="server" href="/deployment/local/onyx_cli">
  Full documentation for `onyx-cli deploy` and its lifecycle commands.
</Card>

## Slash Commands (Interactive TUI)

When using the interactive chat, the following slash commands are available:

| Command | Description |
|---------|-------------|
| `/help` | Show help message |
| `/new` | Start a new chat session |
| `/agent` | List and switch agents |
| `/attach <path>` | Attach a file to next message |
| `/sessions` | List recent chat sessions |
| `/clear` | Clear the chat display |
| `/configure` | Re-run connection setup |
| `/connectors` | Open connectors in browser |
| `/settings` | Open settings in browser |
| `/quit` | Exit Quor CLI |

## Using as an AI Coding Assistant Skill

The Quor CLI can be used as a tool by AI coding assistants (such as Claude Code and Cursor)
to query your knowledge base directly from within your development environment.
A pre-built skill definition is available in the Quor repository at
[`.cursor/skills/onyx-cli/SKILL.md`](https://github.com/onyx-dot-app/onyx/blob/main/cli/internal/embedded/SKILL.md).

Once configured, the AI assistant can call `onyx-cli ask` to look up company-specific information — policies,
internal docs, connected data sources — without leaving the editor.

### When the skill is invoked

The skill is triggered when you ask your AI assistant about:

- Company-specific information (policies, processes, documentation)
- Internal knowledge bases or connected data sources
- Anything referencing Quor, "search Quor", or querying company documents

It is **not** used for general programming questions or questions about code in the current repository.

### Configuration for agents

The simplest approach is to run `onyx-cli configure` once manually — after that,
AI assistants can invoke `onyx-cli ask` directly without any additional setup.

```shell
onyx-cli configure
```

Alternatively, you can configure via environment variables,
which override the config file and are useful for CI/CD or sandboxed environments:

```shell
export ONYX_SERVER_URL="https://your-onyx-server.com"
export ONYX_API_KEY="your-api-key"
```

### JSON output for structured parsing

Use `--json` to get NDJSON event output, which is easier for agents to parse programmatically:

```shell
onyx-cli ask --json "List all active API integrations"
```

| Event Type | Description |
|------------|-------------|
| `message_delta` | Content token — concatenate all `content` fields for the full answer |
| `stop` | Stream complete |
| `error` | Error with `error` message field |
| `search_tool_start` | Quor started searching documents |
| `citation_info` | Source citation with `citation_number` and `document_id` |

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Escape` | Cancel current generation |
| `Ctrl+O` | Toggle source citations |
| `Ctrl+D` | Quit (press twice) |
| `Scroll` / `Shift+Up/Down` | Scroll chat history |
| `Page Up` / `Page Down` | Scroll half page |