Onyx CLI — Agent Tool

onyx-cli is an agent's interface to the Onyx enterprise knowledge platform. It connects to company documents, apps, and people. Use it to answer questions that require internal knowledge — policies, docs, processes, data from connected sources (Confluence, Google Drive, Slack, etc.).

Prerequisites

1. Check if installed

which onyx-cli

2. Install (if needed)

pip install onyx-cli

3. Check if configured

If a human has already run onyx-cli chat (which includes first-time setup), the CLI is ready — no additional setup needed. The config file at ~/.config/onyx-cli/config.json (or $XDG_CONFIG_HOME/onyx-cli/config.json if set) is read automatically.

Environment variables override the config file and can be used as an alternative when no config file exists:

export ONYX_SERVER_URL="https://your-onyx-server.com"  # default: https://cloud.onyx.app
export ONYX_PAT="your-pat"

If neither a config file nor environment variables are set, tell the user that onyx-cli needs to be configured and ask them to either:

• Run onyx-cli chat to complete first-time setup interactively, or
• Set ONYX_SERVER_URL and ONYX_PAT environment variables (ONYX_PAT holds your PAT)

4. Verify configuration

onyx-cli validate-config

Exit code 0 on success. Non-zero with a descriptive error on failure (see exit codes below).

Commands

Search documents

onyx-cli search "What is our deployment process?"

Returns ranked, cited documents from the Onyx knowledge base as JSON. Default output is a lean shape: {"results": [{title, url, source_type, content, updated_at}, ...]}. Results contain only documents the LLM judged relevant, ordered by relevance; content is the full chunk text of each. Use --raw for the full API response (adds per-result citation_id).

# Filter by source
onyx-cli search --source slack,google_drive "auth migration status"

# Recent results only
onyx-cli search --days 30 "recent production incidents"

# Use a specific agent for scoped search
onyx-cli search --agent-id 5 "engineering roadmap"

# Full API response for programmatic use
onyx-cli search --raw "API documentation" | jq '.results[].title'

# Skip query expansion for exact matching
onyx-cli search --no-query-expansion "exact error message text"

Ask a question

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

Streams an LLM-generated answer as plain text to stdout. Use search instead when you need the source documents rather than a synthesized answer. When stdout is not a TTY, output is truncated to 50000 bytes and the full response is saved to a temp file (path printed at the end). Use --max-output 0 to disable truncation.

# Use a specific agent
onyx-cli ask --agent-id 5 "Summarize our Q4 roadmap"

# Pipe context in with the question
cat error.log | onyx-cli ask --prompt "Find the root cause"

# Structured NDJSON output
onyx-cli ask --json "List all active API integrations"

List available agents

onyx-cli agents
onyx-cli agents --json

Prints a table of agent IDs, names, and descriptions. Use --json for structured JSON output. Use agent IDs with search --agent-id or ask --agent-id.

Validate configuration

onyx-cli validate-config

Checks config exists, PAT is present, server is reachable, and credentials are valid. Use before search, ask, or agents to confirm the CLI is properly set up.

Output Conventions

• stdout: Results only (answer text, agent list, status)
• stderr: Progress indicators, warnings, errors
• Non-TTY: No ANSI escape codes, no interactive prompts
• Truncation: When stdout is not a TTY, search and ask output is truncated to 50000 bytes. Full response is saved to a temp file whose path is printed. Read the temp file for more.

Exit Codes

Statelessness

Each invocation is independent. search does not create a chat session. ask creates a one-shot chat session. There is no way to chain context across multiple invocations — every call starts fresh.

When to Use

Use onyx-cli search when:

• You need to find specific documents or gather context for a task
• You want to reason over multiple source documents yourself
• The user asks you to look up or find information in company knowledge
• You need cited, structured results (document IDs, source types, content)

Use onyx-cli ask when:

• The user wants a direct answer, summarization, or synthesis
• A human-readable response is more useful than raw documents
• You need the LLM to reason across sources and produce an answer

Do NOT use either when:

• The question is about general programming knowledge (use your own knowledge)
• The user is asking about code in the current repository (use grep/read tools)
• The user hasn't mentioned Onyx and the question doesn't require internal company data

Examples

# Search for documents
onyx-cli search "What is our deployment process?"
onyx-cli search --source slack "auth migration status"
onyx-cli search --raw "API documentation" | jq '.results[].title'

# Ask for an answer
onyx-cli ask "What are the steps to deploy to production?"
onyx-cli ask --agent-id 3 "What were the action items from last week's standup?"
cat error.log | onyx-cli ask --prompt "What does this error mean?"