Skip to main content
Onyx CLI terminal interface The Onyx CLI is a terminal interface for chatting with your Onyx agents and querying your knowledge base. Built with Go using Bubble Tea, it provides both an interactive TUI and non-interactive commands for scripting and automation.

​
Installation

Or with uv:

PyPI Package

pip install onyx-cli

​
Build from Source

Requires Go 1.26+.

​
Setup

Run the interactive setup to configure your server URL and API key:
This prompts for your Onyx 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. Accounts & Access page showing the Access Tokens section Create Access Token modal with token name and expiration options

​
Environment Variables

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

​
Validate Configuration

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

​
Commands

​
Interactive Chat

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

​
One-Shot Questions

Ask a question and get a response without entering the TUI:
Use --agent-id to target a specific agent:
Use --json for structured NDJSON output (useful for scripting):

​
List Agents

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

​
Slash Commands (Interactive TUI)

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

​
Using as an AI Coding Assistant Skill

The Onyx 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 Onyx repository at .cursor/skills/onyx-cli/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 Onyx, “search Onyx”, 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.
Alternatively, you can configure via environment variables, which override the config file and are useful for CI/CD or sandboxed environments:

​
JSON output for structured parsing

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

​
Keyboard Shortcuts