Omni CLI

Command-line tool for the Omni API. Commands are auto-generated from the OpenAPI spec at build time — no hand-written endpoint wrappers needed.

Installation

Homebrew (macOS / Linux) Preferred

brew tap exploreomni/tap
brew install omni

Install script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/exploreomni/cli/main/install.sh | sh

This downloads the latest release, verifies the SHA-256 checksum, and installs the omni binary to /usr/local/bin (or ~/.local/bin if /usr/local/bin isn't writable).

Download from GitHub Releases

Pre-built binaries for macOS, Linux, and Windows are available on the Releases page. Download the archive for your platform, extract it, and place the omni binary somewhere on your PATH.

Platform	Architectures
macOS	amd64, arm64
Linux	amd64, arm64
Windows	amd64

Build from source

git clone https://github.com/exploreomni/cli.git
cd cli
make build

The binary is written to ./bin/omni.

Quick start

Configure a profile

omni config init

This creates a profile with your organization, API endpoint, and API key. You can create multiple profiles for different orgs or environments.

Set your API token

Omni supports two types of API tokens:

• Organization-wide tokens — shared tokens scoped to an entire org
• Personal access tokens (PATs) — tokens tied to an individual user

Either enter your token during config init, or set the environment variable:

export OMNI_API_TOKEN=omni_osk_...

Run a command

omni models list
omni documents list
omni --help

Shell completions

omni supports tab completion for bash, zsh, fish, and PowerShell. Pick your shell below and run the snippet once — tab completion works on every new shell thereafter.

zsh

Source on every shell start (simplest):

echo 'source <(omni completion zsh)' >> ~/.zshrc

Or install into your fpath for faster startup:

omni completion zsh > "${fpath[1]}/_omni"
# ensure `autoload -U compinit && compinit` runs in your .zshrc

bash

Requires the bash-completion package.

echo 'source <(omni completion bash)' >> ~/.bashrc

System-wide install (Linux):

omni completion bash | sudo tee /etc/bash_completion.d/omni > /dev/null

fish

omni completion fish > ~/.config/fish/completions/omni.fish

PowerShell

omni completion powershell | Out-String | Invoke-Expression

Add that line to your PowerShell profile to persist it across sessions.

After installing, restart your shell and try: omni <TAB>, omni ai <TAB>, omni ai sea<TAB> → omni ai search-omni-docs.

How it works

The CLI embeds the OpenAPI spec (api/openapi.json) into the binary. At startup it parses the spec and generates cobra subcommands for every operation. Each API tag becomes a command group, path params become positional args, query params become flags, and request bodies are passed via --body or stdin.

Flag names are always kebab-case, whatever the spec calls the parameter (branchId and branch_id both become --branch-id). Spelling is forgiving: case, dashes and underscores are ignored when matching, so --branch-id, --branchId, --branch_id and --branchid all set the same flag. --help shows the canonical form.

A query parameter whose name would collide with a global or built-in flag (--token, --base-url, --body, --schema, ...) is registered with a param- prefix instead — a spec parameter named baseUrl becomes --param-base-url, so --base-url keeps meaning the API endpoint. --help notes the rename, and the value is still sent under the spec's own parameter name.

Adding a new API endpoint requires no code changes — update api/openapi.json (or run make sync-spec) and rebuild.

Auth

Auth is resolved with this precedence (highest wins):

1. --token flag
2. OMNI_API_TOKEN env var
3. Profile's apiKey from config file

Config file lives at ~/.config/omni-cli/config.json.

Output

All output is JSON to stdout. Errors go to stderr as JSON. Use --compact for non-indented output (good for piping to jq).

Failures write nothing to stdout — the API's error body, the error message, and any subcommand suggestions go to stderr, and the exit code is non-zero. An empty stdout therefore always means "no data", which keeps omni ... | jq from choking on error JSON.

A failed API call leaves exactly one JSON document on stderr, so omni ... 2>err.json stays parseable:

{
  "error": "bad model id",
  "status": 400,
  "body": { "detail": "bad model id", "code": "INVALID" }
}

body holds the API's own payload and is omitted when the response wasn't JSON. A successful response that isn't JSON — query run streams text/ndjson, and returns CSV or XLSX with a result type — is passed through to stdout unchanged.

Environment variables

Variable	Description
OMNI_API_TOKEN	API token for authentication

Development

make build       # Build the binary
make test        # Run tests
make sync-spec   # Update spec from monorepo
make clean       # Remove built binary