Skip to content
Skills Library
Documents & office · Research

onyx-cli

/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.

Repository
onyx ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: embed.go

What it does and when to use it

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.

Original author description

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 it works

  1. Prerequisites
  2. Commands
  3. Output Conventions
  4. Exit Codes
  5. Statelessness
  6. When to Use
  7. Examples
Original SKILL.md headings · 199 lines, 1,506 words
SKILL.md preview
---
name: onyx-cli
description: 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.
---

# 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

```bash
which onyx-cli
```

### 2. Install (if needed)

```bash
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:

```bash
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

```bash
onyx-cli validate-config
```

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

## Commands

### Search documents

```bash
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.

```bash
# 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"
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"
```

| 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)     |
| `--agent-name`          | string | Agent name for scoped search (exact or unique substring)         |
| `--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

```bash
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.

```bash
# 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"
```

| Flag           | Type | Description                                                  |
| -------------- | ---- | ------------------------------------------------------------ |
| `--agent-id`   | int  | Agent ID to use (overrides default)                          |
| `--agent-name` | str  | Agent name to use (exact or unique substring; mutually exclusive with `--agent-id`) |
| `--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

```bash
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`.

### Validate configuration

```bash
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

```bash
# 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?"
```
Files in this package (2)
  • SKILL.md 10 KB
  • embed.go 1 KB

Versions

The database has no other skills named onyx-cli.

Database snapshot: 13.11.2026 · package version c11ba3f61503 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100craft-documentation
    Answer questions about how Onyx and Onyx Craft work using the official documentation at docs.onyx.app. Use when the user asks what Craft can do, how a feature works, how to set up skills or apps, or how to deploy, configure, or administer Onyx.
  • 100onyx-ai
    Deploy and configure Onyx, a self-hosted AI chat platform with RAG and 25+ data connectors. Use when: setting up private ChatGPT alternative, connecting AI to company documents, building enterprise AI assistant with Confluence/Slack/Drive access.
  • 95onyx-craft-dev
    Start, debug, refresh images, run migrations, and clean up the local Onyx Craft Kubernetes environment with kind, Telepresence, and Make. Use for Craft sandbox development; use the Compose guide when testing the Docker sandbox backend.
  • 100knowledge-base
    Build and maintain a company knowledge base as a wiki of interlinked markdown notes in the workspace — a private, compounding Wikipedia. Use when the user wants to start or organize a knowledge base / wiki, ingest sources (URLs, documents, pasted notes) into it, ask questions…
  • 100boox-bookorbit-setup
    Set up an Onyx Boox e-ink reader (Go 6, Note Air 5C and similar) so Home opens KOReader with the BookOrbit dashboard, books live in one folder, reading progress syncs with a BookOrbit server, and local Boox Notes stay untouched. Use when the user wants to configure a Boox as a…
  • 95pipeshub
    Search and ask questions about the organization's documents — Drive, Slack, Gmail, Jira, Confluence, and the knowledge base. Use whenever a question could be answered by company content rather than general knowledge.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.