CLI

Interact with Onyx from the command line

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

PyPI (recommended)

pip install onyx-cli

Or with uv:

uv pip install onyx-cli

PyPI Package

pip install onyx-cli

Go

go install github.com/onyx-dot-app/onyx/cli@latest

Build from Source

Requires Go 1.24+.

git clone 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:

onyx-cli configure

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.

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.onyx.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:

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

Interactive Chat

onyx-cli

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:

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

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

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

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

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

onyx-cli agents
onyx-cli agents --json

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:

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 Onyx CLI

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.

onyx-cli configure

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

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:

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	Onyx 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