Onyx CLI

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

Flag	Description
`--no-stream-markdown`	Disable progressive markdown rendering during streaming

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 --json "Hello"

Flag	Description
`--agent-id <int>`	Agent ID to use (overrides default)
`--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

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

CI release (recommended)

Tag a release and push — the release-cli.yml workflow builds wheels for all platforms and publishes to PyPI automatically:

tag --prefix cli

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

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.

License
- OSI Approved :: MIT License
Operating System
Programming Language
- Go

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

onyx_cli-1.3.1-py3-none-win_arm64.whl (4.6 MB view details)

Uploaded Jul 29, 2026 Python 3Windows ARM64

onyx_cli-1.3.1-py3-none-win_amd64.whl (5.1 MB view details)

Uploaded Jul 29, 2026 Python 3Windows x86-64

onyx_cli-1.3.1-py3-none-musllinux_1_2_x86_64.whl (5.0 MB view details)

Uploaded Jul 29, 2026 Python 3musllinux: musl 1.2+ x86-64

onyx_cli-1.3.1-py3-none-musllinux_1_2_aarch64.whl (4.5 MB view details)

Uploaded Jul 29, 2026 Python 3musllinux: musl 1.2+ ARM64

onyx_cli-1.3.1-py3-none-manylinux_2_17_x86_64.whl (5.0 MB view details)

Uploaded Jul 29, 2026 Python 3manylinux: glibc 2.17+ x86-64

onyx_cli-1.3.1-py3-none-manylinux_2_17_aarch64.whl (4.5 MB view details)

Uploaded Jul 29, 2026 Python 3manylinux: glibc 2.17+ ARM64

onyx_cli-1.3.1-py3-none-macosx_11_0_arm64.whl (4.7 MB view details)

Uploaded Jul 29, 2026 Python 3macOS 11.0+ ARM64

onyx_cli-1.3.1-py3-none-macosx_10_12_x86_64.whl (5.0 MB view details)

Uploaded Jul 29, 2026 Python 3macOS 10.12+ x86-64

File details

Details for the file onyx_cli-1.3.1-py3-none-win_arm64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-win_arm64.whl
Upload date: Jul 29, 2026
Size: 4.6 MB
Tags: Python 3, Windows ARM64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-win_arm64.whl
Algorithm	Hash digest
SHA256	`8857dc3d468cf1f21d9c68f0d16191edd0482a8811a25bd0505be84dc2484c38`
MD5	`11fd7900ed2b2a0740cf2f32afbac494`
BLAKE2b-256	`0f707ae9be8b87c76cbdbc6aff5deb625b4cddaf17f009ba72d2f5861610bd3d`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-win_amd64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-win_amd64.whl
Upload date: Jul 29, 2026
Size: 5.1 MB
Tags: Python 3, Windows x86-64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`fff12da777660c647017610bdbd44d0281c98ad53c3e80254ad5f8772cc8ae63`
MD5	`166f24980382a87d8a0c27468c776ede`
BLAKE2b-256	`4bd5f4e499b3f952bf2652cda8898f3787f417bf06dc74fd80cf30e176ebee12`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-musllinux_1_2_x86_64.whl
Upload date: Jul 29, 2026
Size: 5.0 MB
Tags: Python 3, musllinux: musl 1.2+ x86-64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm	Hash digest
SHA256	`ba5a967fb5945dfbb8d42843f54e404cc3a30bbe8178ef9a8865cea499ed4038`
MD5	`512028207313f05b9291cf9a6395d237`
BLAKE2b-256	`be58d4eb06ebb4bc9bac012728f377868df5a836c2ae8939c923329ed25675a2`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-musllinux_1_2_aarch64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-musllinux_1_2_aarch64.whl
Upload date: Jul 29, 2026
Size: 4.5 MB
Tags: Python 3, musllinux: musl 1.2+ ARM64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-musllinux_1_2_aarch64.whl
Algorithm	Hash digest
SHA256	`63d8a16e27d927a5d812a7bc86d81571e136798c39e90d5d02bf18e9ed32bfb5`
MD5	`1fb691aa7efeca666f5e33ed43c2d65c`
BLAKE2b-256	`5faf8af293a0484b1bb755c4961bdc15dea995ea946f9f739d925cbf56c3c989`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-manylinux_2_17_x86_64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-manylinux_2_17_x86_64.whl
Upload date: Jul 29, 2026
Size: 5.0 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-manylinux_2_17_x86_64.whl
Algorithm	Hash digest
SHA256	`fcf9616d48adec23c5fafb6dfc9e7b48efce8ad38d4aa60adfd05e0df36faba3`
MD5	`db0d9684ea8f613b509bb6c45fa821d0`
BLAKE2b-256	`66d091fd81c99e1ae43cde0f588404f272d1ab65ab1b002415b6ecfb08914017`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-manylinux_2_17_aarch64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-manylinux_2_17_aarch64.whl
Upload date: Jul 29, 2026
Size: 4.5 MB
Tags: Python 3, manylinux: glibc 2.17+ ARM64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-manylinux_2_17_aarch64.whl
Algorithm	Hash digest
SHA256	`1cf077aa3ab3bc21b339ba464e1687054cf54387008470a47830d737b3ff4826`
MD5	`78f00182b24833ec9e4bb460de84b809`
BLAKE2b-256	`1701f5ae2780a2b662a5b185a83b59e6e7f7c7d44719c49bd47f62c631007050`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-macosx_11_0_arm64.whl
Upload date: Jul 29, 2026
Size: 4.7 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`b5154e8d0bfa2fd2c74935dab50f78bae558f7982ad8db0533660ab181cf515e`
MD5	`5f1ddd4bb326bed21b68fd1b4c6ea4ce`
BLAKE2b-256	`798cb6ef6e4ab61af9bd24bae8f354fc72bee286378f0e39698c33e0e5453208`

See more details on using hashes here.

File details

Details for the file onyx_cli-1.3.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

Download URL: onyx_cli-1.3.1-py3-none-macosx_10_12_x86_64.whl
Upload date: Jul 29, 2026
Size: 5.0 MB
Tags: Python 3, macOS 10.12+ x86-64
Uploaded using 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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for onyx_cli-1.3.1-py3-none-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`0f03d8218af3444664bdf3067553d32d62771c20e2dc73aed3d6c9bb986c1a89`
MD5	`c17b70b08af52a844cc8da54e0428ae7`
BLAKE2b-256	`b243dca0579ac1c85abd7ecef2642c52263f4d555e4f2ec23cde483a0586ad08`

See more details on using hashes here.

Release history Release notifications | RSS feed

1.3.4

Aug 4, 2026

1.3.3

Aug 3, 2026

1.3.2

Jul 30, 2026

This release

1.3.1

Jul 29, 2026

1.3.0

Jul 29, 2026

1.2.3

Jul 23, 2026

1.2.2

Jul 8, 2026

1.2.1

Jun 29, 2026

1.2.0

Jun 29, 2026

1.1.1

Jun 12, 2026

1.1.0

Jun 12, 2026

1.0.4

May 29, 2026

1.0.3

May 14, 2026

1.0.2

May 13, 2026

1.0.1

May 12, 2026

1.0.0

May 12, 2026

0.3.1

May 9, 2026

0.2.1

Apr 3, 2026

0.2.0

Mar 27, 2026

0.1.2

Mar 27, 2026

0.1.1

Mar 7, 2026

0.1.0

Mar 6, 2026

onyx-cli 1.3.1

Onyx CLI

Installation

Setup

Usage

Interactive chat

One-shot question

List agents

Serve over SSH

Commands

Global Flags

Agent / Non-Interactive Use

Configuration

Exit Codes

Skill File

Slash Commands (in TUI)

Keyboard Shortcuts

Building from Source

Development

Publishing to PyPI

CI release (recommended)

Manual release

Versioning

Project links

Key dates

2 maintainers

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

Release history Release notifications | RSS feed