Command-line interface

celeris is the official command-line interface for the Celeris API. It is built for shell pipelines: inputs come from flags, @files, or stdin; results go to stdout; diagnostics go to stderr. If you have used the OpenAI CLI, the command layout will feel familiar.

Install

With Homebrew (macOS and Linux):

brew install ai-celeris/tools/celeris

With Go 1.23 or later:

go install github.com/ai-celeris/celeris-cli/cmd/celeris@latest

Prebuilt archives for macOS, Linux, and Windows are on the releases page, with checksums.

Configure

The CLI reads your API key from CELERIS_API_KEY:

export CELERIS_API_KEY="ck_..."

That is the only required setting; the CLI targets the production endpoint by default. CELERIS_BASE_URL overrides the endpoint (the CLI appends /v1 itself), CELERIS_MODEL overrides the default model (celeris-1), and OPENAI_API_KEY / OPENAI_BASE_URL work as fallbacks. Every setting also has a flag: --api-key, --base-url, --model.

First request

celeris q "Reply with one word: the capital of France."

Paris

q is the pipeline shortcut: it sends one user message, streams the answer as plain text, and appends piped stdin to the prompt as context:

git diff --staged | celeris q "Write a one-line commit message for this diff:"
tail -100 app.log | celeris q "Summarize the errors in this log:"

The full API surface

The resource commands mirror the HTTP API and print the complete response:

# Chat completions, non-streaming, full JSON response:
celeris chat:completions create \
  --input "Classify as positive or negative: great product" \
  --max-tokens 256 --temperature 0 \
  --format json

# System prompts and multi-turn conversations:
celeris chat:completions create \
  -g system:"Answer tersely." \
  -g user:"What is a monad?" \
  --stream

# Legacy completions:
celeris completions create --prompt "The capital of France is" --max-tokens 256

# Models:
celeris models list

# Anything else under /v1, as a raw authenticated request:
echo '{"model":"celeris-1","messages":[{"role":"user","content":"hi"}]}' \
  | celeris api post /chat/completions

Input flags accept a literal value, @file to read a file, or - to read stdin. With no input flag, piped stdin becomes the user message.

Output formats

--format controls what lands on stdout:

Format	Output
auto	Pretty JSON on a terminal; bare text when piped (default)
text	The completion text only
json	The full response as compact JSON
jsonl	One JSON object per line (stream chunks, or models)
pretty	Indented JSON, or a table for models list on a terminal
raw	The response body exactly as received

--stream emits tokens as they are generated; with --format jsonl it prints each chunk's JSON on its own line instead.

Exit codes are 0 for success, 1 for request or API failures, and 2 for usage errors, so scripts can tell a bad invocation from a failed call. Error messages, including Retry-After on 429 responses, go to stderr.

Request limits

The CLI validates max_tokens before sending: it must be a positive multiple of 256, and prompt plus completion must fit the 8192-token context window.

Debugging

Every request carries a User-Agent that identifies the CLI build, such as celeris-cli/1.2.3 (darwin; arm64) go/1.23.4. If you report an issue, include your celeris version output; support can correlate it with server-side request logs. --debug prints the request method, URL, User-Agent, and body to stderr:

celeris models list --debug

Version and updates

celeris version
brew upgrade celeris   # Homebrew installs

The CLI is open development at github.com/ai-celeris/celeris-cli; releases follow semantic versioning.