ai

One-shot CLI for OpenAI-compatible chat endpoints.

Quick start

Create a default config:

ai --init

Edit the generated file at $XDG_CONFIG_HOME/ai/config.toml (or ~/.config/ai/config.toml), then run:

ai "hello from cli"

You can also pipe stdin:

echo "summarize this" | ai

Flags

• --model NAME select a model from [models] for one call.
• --prompt NAME select a preset prompt from [prompts] for one call.
• --minimal disable status output and thinking colorization for that invocation.
• --strip-thinking remove thinking text from output (before colorization).
• --init create a default config file.
• --history N replay the N-th most recent response to stdout (1 = last). Colorization obeys --minimal.
• --history-clear delete stored history.
• --list-models print available model names from config.
• --list-prompts print available prompt names from config.
• --completions <shell> print shell completions (bash, zsh, fish).

Config

The client reads $XDG_CONFIG_HOME/ai/config.toml (falls back to ~/.config/ai/config.toml).

Example

[defaults]
model = "openai"
prompt = "concise"
minimal = false
strip_thinking = false
thinking_delimiters = [
  { start = "<think>", end = "</think>" },
  { start = "[thought]", end = "[/thought]" },
]

[history]
enabled = true
max_entries = 100

[prompts.concise]
text = "Be concise and direct."

[models.openai]
endpoint = "https://api.openai.com"
model = "gpt-4o-mini"
system_prompt = "You are a helpful assistant."
api_key_command = "pass show openai/api-key"
options = "{\"reasoning\":{\"enabled\":true}}"
strip_thinking = false
thinking_delimiters = [
  { start = "<think>", end = "</think>" },
]

Notes

• endpoint accepts either https://host or https://host/v1 or full /v1/chat/completions.
• api_key and api_key_command are mutually exclusive.
• defaults.prompt is required; use an empty prompt text if you want no additional preset prompt.
• system_prompt (model system prompt) is always applied first.
• The selected named prompt (preset prompt) is applied next.
• The user input (CLI args or stdin) is applied last.
• options (per model) is a raw JSON object merged into the request body; it cannot override model or messages.
• strip_thinking can be set in defaults or per model; --strip-thinking forces it on.
• If the API returns a separate reasoning field, it is injected before the main content using the configured thinking delimiters (unless the content already contains delimiters).
• If a response contains only the end delimiter (no start), everything up to that end delimiter is treated as thinking text.
• history is stored in $XDG_CACHE_HOME/ai/history.json.

Building

Release build:

cargo build --release

Static binary (example for musl on Linux):

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Shell completions

Generate and install (examples):

ai --completions bash > /etc/bash_completion.d/ai

ai --completions zsh > /usr/local/share/zsh/site-functions/_ai

ai --completions fish > ~/.config/fish/completions/ai.fish