skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
onyx-dot-app/onyx57 installs

onyx-cli

Query the Onyx knowledge base using the onyx-cli command. Use when the user wants to search company documents, ask questions about internal knowledge, query connected data sources, or look up information stored in Onyx.

How do I install this agent skill?

npx skills add https://github.com/onyx-dot-app/onyx --skill onyx-cli
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The onyx-cli skill allows an agent to query internal knowledge bases. While it follows standard security practices for authentication and configuration, it is susceptible to indirect prompt injection because it processes untrusted content from external sources like Slack and Confluence.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

  • Runlayerpass

    1/1 file flagged

What does this agent skill do?

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"
VariableRequiredDescription
ONYX_SERVER_URLNoServer origin or already-prefixed API base (default: https://cloud.onyx.app)
ONYX_API_PREFIXNoAPI path prefix (default: /api); empty for direct backend access
ONYX_PATYesPersonal access token for authentication (unless config file exists)
ONYX_PERSONA_IDNoDefault agent/persona ID
ONYX_STREAM_MARKDOWNNoEnable/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"

# Limit to document sets (list names with `onyx-cli document-sets`)
onyx-cli search --document-set "Engineering Wiki" "on-call runbook"

# 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"
onyx-cli search --agent-name "Support Agent" "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"
FlagTypeDescription
--sourcestringFilter by source type (comma-separated: slack,google_drive)
--document-setstringFilter by document set name. Repeat the flag for more than one set; commas are part of the name. Replaces the default agent's knowledge scope; cannot be combined with --agent-id or --agent-name
--daysintOnly return results from the last N days
--agent-idintAgent ID for scoped search (inherits filters, document sets)
--agent-namestringAgent name for scoped search (exact or unique substring)
--rawboolOutput full API response (adds per-result citation_id)
--no-query-expansionboolSkip LLM query expansion — faster, but only safe when the query is already precise (exact names, titles, quoted phrases)
--max-outputintMax 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"
onyx-cli ask --agent-name "Support Agent" "hello"

# 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"
FlagTypeDescription
--agent-idintAgent ID to use (overrides default)
--agent-namestrAgent name to use (exact or unique substring; mutually exclusive with --agent-id)
--jsonboolOutput NDJSON stream events instead of plain text (bypasses truncation)
--quietboolBuffer output and print once at end (no streaming)
--promptstrQuestion text (use with piped stdin context)
--max-outputintMax bytes to print before truncating (0 to disable, default 50000 for non-TTY)
--approvestrAnswer to tool approval requests: fail (default), reject, once, or session
--questionsstrAnswer to the agent's questions: fail (default) or skip

Tool approvals

Some tool calls need the user's approval before they run. Without a terminal, ask never waits for input. It uses --approve:

  • fail (default): rejects the tool call, prints the rest of the answer without it, and exits with code 10. Without --json, it prints the request to stderr. With --json, the request is the tool_approval_request event on stdout.
  • reject: rejects the tool call and continues the answer without it.
  • once or session: approves every tool call in the response that needs approval.

After the answers, ask follows the response as it continues and prints the rest of the answer in the same run.

On exit code 10, show the user the tool name and arguments. Without --json, read them from stderr, which shows at most 10 arguments and shortens long values; say so when it does. With --json, read them from the tool_approval_request event on stdout, which has every argument in full. On a terminal, the user can answer d to see every argument in full. A new run gives a new response, which can request different tool calls. Consent to the tool call that the user saw is not consent to --approve=once or --approve=session, because these approve every tool call in the new run without showing it. Use them only if the user agrees to approve all tool calls in the run. Otherwise, ask the user to run the command on a terminal, where ask shows each request and waits for an answer.

Questions from the agent

The agent can ask the user 1 to 3 multiple-choice questions. Without a terminal, ask never waits for input. It uses --questions, and both values tell the agent that no one can answer, so it continues with its own judgment:

  • fail (default): prints the rest of the answer and exits with code 12. Without --json, it prints the questions and their numbered choices to stderr. With --json, the questions are the tool_question_request event on stdout.
  • skip: prints the rest of the answer and exits normally.

On exit code 12, show the user the questions and choices. To answer them, run ask again with the answers in the question text, or ask the user to run the command on a terminal, where ask prompts for each question. A new run gives a new response, which can ask different questions.

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 --agent-id, or names with --agent-name, on ask, search, and chat.

List document sets

onyx-cli document-sets
onyx-cli document-sets --json

Prints the document sets the current user can search: ID, name, and description. Use --json for structured JSON output ([{id, name, description}, ...]). Pass the names to onyx-cli search --document-set. A name the user cannot access makes the search fail instead of returning unfiltered results.

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

CodeNameMeaning
0SuccessCommand completed successfully
1GeneralUnknown or unclassified error
2BadRequestInvalid arguments
3NotConfiguredMissing config or PAT
4AuthFailureInvalid PAT (401/403)
5UnreachableServer unreachable
6RateLimitedServer returned 429
7TimeoutRequest timed out
8ServerErrorServer returned 5xx
9NotAvailableFeature/endpoint does not exist
10ApprovalRequiredA tool call needed approval; --approve=fail rejected it
11ApprovalPendingask was interrupted at an approval or question prompt; the request still waits for the user
12QuestionUnansweredThe agent asked questions; --questions=fail answered that no one can answer

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

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/onyx-dot-app/onyx/onyx-cli">View onyx-cli on skillZs</a>