Onyx CLI

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  # default: https://cloud.onyx.app
export

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 — printed bare for one query (adds per-result citation_id), and as {"searches": [{query, response}, ...]} for several.

Each query is a full search pass that takes tens of seconds. Multiple queries passed in one invocation (up to 3) run concurrently — batch independent questions into a single call instead of running them sequentially. Multi-query output is {"searches": [{query, results}, ...]} in argument order; a failed query has an error field and null results, and partial failures still exit 0, so check per-query error fields. Write search output to files and parse it in a separate shell call — a parsing script (e.g. a Python heredoc) chained after a search can hang, hit your shell timeout, and throw away the completed searches.

Stdout is always valid JSON. If the response exceeds --max-output bytes (default 50000 for non-TTY), lowest-ranked results are dropped and a truncation object is added: {truncated, total_results, shown_results, total_bytes, content_truncated, full_response_path, hint}. The complete response — shaped like the printed output (results for one query, searches for several) — is saved to full_response_path; read that file for the dropped results. With multiple queries, per-query result counts are capped uniformly until the combined output fits, so small result sets pass through whole.

# Batch independent questions (concurrent)
onyx-cli search "Q3 roadmap" "hiring plan" "incident postmortem template"

# 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 limited to 50000 bytes and the full response is saved to a temp file. search stays valid JSON — whole results are dropped and a truncation object carries the temp file path. ask (plain text) is cut at the byte limit with the temp file path printed at the end.

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?"