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"

Variable	Required	Description
ONYX_SERVER_URL	No	Server origin or already-prefixed API base (default: https://cloud.onyx.app)
ONYX_API_PREFIX	No	API path prefix (default: /api); empty for direct backend access
ONYX_PAT	Yes	Personal access token for authentication (unless config file exists)
ONYX_PERSONA_ID	No	Default agent/persona ID
ONYX_STREAM_MARKDOWN	No	Enable/disable progressive markdown rendering (true/false)

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"

Flag	Type	Description
--source	string	Filter by source type (comma-separated: slack,google_drive)
--days	int	Only return results from the last N days
--agent-id	int	Agent ID for scoped search (inherits filters, document sets)
--raw	bool	Output full API response (adds per-result citation_id)
--no-query-expansion	bool	Skip LLM query expansion — faster, but only safe when the query is already precise (exact names, titles, quoted phrases)
--max-output	int	Max bytes to print before truncating (0 to disable, default 50000 for non-TTY, ignored with --raw)

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"

Flag	Type	Description
--agent-id	int	Agent ID to use (overrides default)
--json	bool	Output NDJSON stream events instead of plain text (bypasses truncation)
--quiet	bool	Buffer output and print once at end (no streaming)
--prompt	str	Question text (use with piped stdin context)
--max-output	int	Max bytes to print before truncating (0 to disable, default 50000 for non-TTY)

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

Code	Name	Meaning
0	Success	Command completed successfully
1	General	Unknown or unclassified error
2	BadRequest	Invalid arguments
3	NotConfigured	Missing config or PAT
4	AuthFailure	Invalid PAT (401/403)
5	Unreachable	Server unreachable
6	RateLimited	Server returned 429
7	Timeout	Request timed out
8	ServerError	Server returned 5xx
9	NotAvailable	Feature/endpoint does not exist

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