Skip to main content

Onyx CLI

Release CLI PyPI

A CLI for querying enterprise knowledge from Onyx. Includes an interactive chat TUI for humans and non-interactive commands for AI agents and scripts.

Installation

pip install onyx-cli

Or with uv:

uv pip install onyx-cli

Standalone binaries for Linux, macOS, and Windows (amd64/arm64) are also attached to each cli/v* GitHub release.

Setup

Run the interactive chat TUI — on first launch it will guide you through setup:

onyx-cli chat

This prompts for your Onyx server URL and personal access token (PAT), tests the connection, and saves config to ~/.config/onyx-cli/config.json (or $XDG_CONFIG_HOME/onyx-cli/config.json if set). To reconfigure later, use the /configure command inside the TUI.

Environment variables override config file values:

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); set to empty for direct backend access
ONYX_PAT No Personal access token for authentication (required if no config file)
ONYX_PERSONA_ID No Default agent/persona ID
ONYX_STREAM_MARKDOWN No Enable/disable progressive markdown rendering (true/false)
ONYX_SSH_HOST_KEY No Path to SSH host key for serve command

Usage

Interactive chat

onyx-cli chat
onyx-cli chat --no-stream-markdown
onyx-cli chat --agent-name "Support Agent"
Flag Description
--no-stream-markdown Disable progressive markdown rendering during streaming
--agent-id <int> Agent ID to use for this session
--agent-name <string> Agent name to use for this session (exact or unique substring; mutually exclusive with --agent-id)

One-shot question

onyx-cli ask "What is our company's PTO policy?"
onyx-cli ask --agent-id 5 "Summarize this topic"
onyx-cli ask --agent-name "Support Agent" "hello"
onyx-cli ask --json "Hello"
Flag Description
--agent-id <int> Agent ID to use (overrides default)
--agent-name <string> Agent name to use (exact or unique substring; mutually exclusive with --agent-id)
--json Output NDJSON stream events instead of plain text
--prompt <string> Question text (use with piped stdin context)
--quiet Buffer output and print once at end
--max-output <int> Max bytes before truncating (0 to disable)

List agents

onyx-cli agents
onyx-cli agents --json

List document sets

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

Pass the names to onyx-cli search --document-set to limit a search to those document sets.

Serve over SSH

# Start a public SSH endpoint for the CLI TUI
onyx-cli serve --host 0.0.0.0 --port 2222

# Connect as a client
ssh your-host -p 2222

Clients can either:

  • paste a personal access token (PAT) at the login prompt, or
  • skip the prompt by sending ONYX_PAT over SSH:
export ONYX_PAT=your-pat
ssh -o SendEnv=ONYX_PAT your-host -p 2222

Useful hardening flags:

  • --host-key (default ~/.config/onyx-cli/host_ed25519)
  • --idle-timeout (default 15m)
  • --max-session-timeout (default 8h)
  • --rate-limit-per-minute (default 20)
  • --rate-limit-burst (default 40)
  • --rate-limit-cache (default 4096)

Commands

Command Mode Description
chat Interactive Launch the interactive chat TUI (requires terminal)
ask Agent / Script Ask a question and print the answer to stdout
agents Agent / Script List available agents (ID, name, description)
document-sets Agent / Script List document sets you can search (ID, name, description)
validate-config Agent / Script Check CLI configuration and server connectivity
install-skill Agent / Script Install the Onyx CLI agent skill file
experiments Agent / Script List experimental features and their status
serve Interactive Serve the Onyx TUI over SSH

Global Flags

Flag Description
--version, -v Print client and server version information
--debug Run in debug mode (verbose logging)

Agent / Non-Interactive Use

When called without a TTY (e.g., by an AI agent or piped into another command), onyx-cli adjusts its behavior:

  • No subcommand: prints help and exits 0 (instead of launching the TUI)
  • Results to stdout, progress/errors to stderr
  • No ANSI codes or interactive prompts
  • ask output truncated to 50000 bytes by default; full response saved to a temp file. Use --max-output 0 to disable.
  • search stdout stays valid JSON: over the limit, whole results are dropped and a truncation object carries metadata plus the temp file path of the full response.

Configuration

If a human has already run onyx-cli chat (which includes first-time setup), the CLI works out of the box — no additional setup needed. Environment variables can override the config file or serve as an alternative when no config file exists:

export ONYX_SERVER_URL="https://your-onyx-server.com"
export ONYX_PAT="your-pat"

Exit Codes

Code Name When
0 Success Command completed
1 General Unknown error
2 BadRequest Invalid arguments
3 NotConfigured Missing config/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 doesn't exist

Skill File

Install the bundled SKILL.md so AI coding agents can discover the CLI:

onyx-cli install-skill
onyx-cli install-skill --global
onyx-cli install-skill --copy
onyx-cli install-skill --agent claude-code
Flag Description
--global, -g Install to home directory instead of project
--copy Copy files instead of symlinking
--agent, -a Target specific agents (e.g. claude-code; can be repeated)

Slash Commands (in TUI)

Command Description
/help Show help message
/clear Clear chat and start a new session
/agent List and switch agents (by ID or name)
/attach <path> Attach a file to next message
/sessions List recent chat sessions
/configure Re-run connection setup
/connectors Open connectors in browser
/settings Open settings in browser
/quit Exit Onyx CLI

Keyboard Shortcuts

Key Action
Enter Send message
Escape Cancel current generation
Ctrl+O Toggle source citations
Ctrl+D Quit (press twice)
Scroll / Shift+Up/Down Scroll chat history
Page Up / Page Down Scroll half page

Building from Source

Requires Go 1.24+.

cd cli
go build -o onyx-cli .

Development

# Run tests
go test ./...

# Build
go build -o onyx-cli .

# Lint
golangci-lint run ./...

Publishing to PyPI

The CLI is distributed as a Python package via PyPI. The build system uses hatchling with manygo to cross-compile Go binaries into platform-specific wheels.

Tag a release and push — the release-cli.yml workflow builds wheels for all platforms and publishes to PyPI automatically. ods release cli calculates and pushes the next tag for you:

ods release cli              # bumps the patch version
ods release cli --bump minor
ods release cli --version 1.5.0
ods release cli --dry-run    # computes the version, tags nothing

To do this manually:

git tag cli/v0.1.0
git push origin cli/v0.1.0

The workflow builds wheels for:

  • linux/amd64 manylinux
  • linux/amd64 musllinux
  • linux/arm64 manylinux
  • linux/arm64 musllinux
  • darwin/amd64
  • darwin/arm64
  • windows/amd64
  • windows/arm64

Manual release

Build a wheel locally with uv. Set GOOS and GOARCH to cross-compile for other platforms (Go handles this natively — no cross-compiler needed):

# Build for current platform
uv build --wheel

# Cross-compile for a different platform
GOOS=linux GOARCH=amd64 uv build --wheel

# Build a musllinux-tagged Linux wheel for Alpine/musl environments
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
  ONYX_CLI_WHEEL_PLATFORM_TAG=musllinux_1_2_x86_64 \
  uv build --wheel

# Upload to PyPI
uv publish

Build constraints

The release workflows build every wheel against tools/requirements/build-constraints.txt, shared by cli, tools/ods and tools/ods-audit. They pass it as UV_BUILD_CONSTRAINT with UV_REQUIRE_HASHES, so the build environment (hatchling, go-bin, manygo and their dependencies) is pinned and verified.

A plain local uv build resolves those dependencies freely. Set the same variables to build against the pinned closure:

UV_BUILD_CONSTRAINT="$(git rev-parse --show-toplevel)/tools/requirements/build-constraints.txt" \
  UV_REQUIRE_HASHES=true GOTOOLCHAIN=local \
  uv build --wheel

tools/requirements/build-constraints.txt is compiled from its .in by the pip-compile pre-commit hook, so a plain pre-commit run pip-compile refreshes it. To upgrade a pinned build dependency, edit build-constraints.in and the matching [build-system] requires in all three pyproject.toml files; the build-constraints-drift hook fails if they disagree.

go-bin ships the Go toolchain used to compile the binary. Bumping Go means moving it everywhere at once: the go directive in go.mod, cli/Dockerfile, the setup-go and GO_VERSION pins across .github/workflows/, .devcontainer/Dockerfile, the go-bin pin in all three pyproject.toml files and in tools/requirements/build-constraints.in, and the compiled build-constraints.txt.

Versioning

Versions are derived from git tags with the cli/ prefix (e.g. cli/v0.1.0). The tag is parsed by internal/_version.py and injected into the Go binary via -ldflags at build time.

Chat completion and cancellation

The interactive client keeps the current request active until the server confirms that its session is idle. A STOP packet or a closed connection does not confirm a saved turn. Temporary readiness failures keep Send blocked and retry. Unsupported or denied requests stop polling and show an error. Session, agent, and model pickers remain available while Send is blocked. Reopening the active session preserves its live messages and readiness check. Failed drafts remain in the input. The ask command confirms idle before naming the saved conversation.

Cancellation waits for the response ID before sending Stop. The request owns that ID, so a delayed Stop cannot cancel a later turn. If acknowledgement never arrives, cancellation closes delivery after ten seconds without sending an unscoped Stop. For acknowledged runs, delivery closes after the bounded Stop request completes. Session and response identities remain available after cancellation so the next message can continue from the cancelled turn.

Metadata

Release files for onyx-cli 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for onyx-cli 1.5.0
File Actions
onyx_cli-1.5.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for onyx_cli-1.5.0-py3-none-win_arm64.whl
onyx_cli-1.5.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for onyx_cli-1.5.0-py3-none-win_amd64.whl
onyx_cli-1.5.0-py3-none-musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64 Details for onyx_cli-1.5.0-py3-none-musllinux_1_2_x86_64.whl
onyx_cli-1.5.0-py3-none-musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64 Details for onyx_cli-1.5.0-py3-none-musllinux_1_2_aarch64.whl
onyx_cli-1.5.0-py3-none-manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for onyx_cli-1.5.0-py3-none-manylinux_2_17_x86_64.whl
onyx_cli-1.5.0-py3-none-manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for onyx_cli-1.5.0-py3-none-manylinux_2_17_aarch64.whl
onyx_cli-1.5.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for onyx_cli-1.5.0-py3-none-macosx_11_0_arm64.whl
onyx_cli-1.5.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for onyx_cli-1.5.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 40.9 MB

Release files / onyx_cli-1.5.0-py3-none-win_arm64.whl

Download URL onyx_cli-1.5.0-py3-none-win_arm64.whl
Size 4.9 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
43ae1984082804f3da6a6f12f08b67eb994ab7ee0055163dd782e8b140e8a65e
BLAKE2b-256 checksum
How to use checksums
9137ebf5306d680d6c68d032aff1aa592087c519a7729c894b5fa419c12ec1f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-win_amd64.whl

Download URL onyx_cli-1.5.0-py3-none-win_amd64.whl
Size 5.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
3680dfb29056ecb710b5f7a61d8b3aca89de33ed038fab421debeec65c8bd4ef
BLAKE2b-256 checksum
How to use checksums
53449553d8a2c6020b7f873164f26b3e51c84e10d2bb1d1e40584a80e16d3989
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-musllinux_1_2_x86_64.whl

Download URL onyx_cli-1.5.0-py3-none-musllinux_1_2_x86_64.whl
Size 5.3 MB
Tags Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
3ec5b621b8d2924e8117bbd58a2766a38c75557575e5f7e4a52f4b0451aa0099
BLAKE2b-256 checksum
How to use checksums
4b8b115f14dfbc811b9603d89480c0c48c677eab21f5ca6ae2e267a3d82a8a35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-musllinux_1_2_aarch64.whl

Download URL onyx_cli-1.5.0-py3-none-musllinux_1_2_aarch64.whl
Size 4.8 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
bf1941fce237ca5ac81000d29d917ecd6c57bfaa6f05c0887050231602bcf858
BLAKE2b-256 checksum
How to use checksums
baab387366c3232ea76c1b2ff0e7fe311d0fb1ace0128927d423a921c71815f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-manylinux_2_17_x86_64.whl

Download URL onyx_cli-1.5.0-py3-none-manylinux_2_17_x86_64.whl
Size 5.3 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
7a2905702ce36a7e9de8b557f9e4f9e9c902326e6e43ece5207784a19b59fd34
BLAKE2b-256 checksum
How to use checksums
8ec583873d475d2ba816d83d2964af5e88132364fdc6393f9fe5b2f8d2c31fa4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-manylinux_2_17_aarch64.whl

Download URL onyx_cli-1.5.0-py3-none-manylinux_2_17_aarch64.whl
Size 4.8 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
993e64cbee6b5d2e0c29e82bdfee3d31c146419c0c8d699cde5c03c5d05a306f
BLAKE2b-256 checksum
How to use checksums
76ac5b77862effe7bbe029e159f674aa6d38659c95b3dfed81564f6d967c9409
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-macosx_11_0_arm64.whl

Download URL onyx_cli-1.5.0-py3-none-macosx_11_0_arm64.whl
Size 5.0 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
a3fc7f0e0131afef85cb7c8abf16663cddb343275a9c6b5b51983fd969953490
BLAKE2b-256 checksum
How to use checksums
3c037889eda4b493d426013b43199f30a122193e1a7b736ee88d6cb6d3284df4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / onyx_cli-1.5.0-py3-none-macosx_10_12_x86_64.whl

Download URL onyx_cli-1.5.0-py3-none-macosx_10_12_x86_64.whl
Size 5.4 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
2f3dda751113321bffd1a236bfb6b3dfb782f258141c17d563e7066182b5f6d8
BLAKE2b-256 checksum
How to use checksums
5776bce580dd8e516078bee37d00cca65d03fa6fcd1095089f0903dc81e30408
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for onyx-cli 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page