ai-cli is a multi-provider AI chat client for the command line. It supports local models via Ollama, cloud APIs like OpenAI and Groq, and any OpenAI-compatible endpoint — all through a single binary with streaming, piping, session persistence, and shell completions.

Highlights

• 5 providers out of the box — Ollama, OpenAI, Groq, LocalAI, and any custom OpenAI-compatible API
• Streaming responses — tokens appear as they arrive, with a spinner during latency
• Pipe-friendly — cat file.go | ai-cli openai "review this code" works as expected
• Conversation persistence — sessions auto-save as JSONL; list, continue, export, or delete them
• Shell completions — dynamic model name completion via --model <TAB>
• JSON output — --output json for scripting and automation
• Zero config to start — ai-cli ollama "hello" works immediately if Ollama is running

Install

Homebrew

brew install ahr9n/tap/ai-cli

Go

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

Binary

Download a prebuilt binary from Releases.

Source

git clone https://github.com/ahr9n/ai-cli.git && cd ai-cli
make build && make install

Requires Go 1.24+.

Providers

Use --url to point any provider at a custom endpoint (vLLM, LM Studio, OpenRouter, etc.)

Quick Start

# Single prompt
ai-cli ollama "What is the capital of Palestine?"

# Cloud provider
export OPENAI_API_KEY=sk-...
ai-cli openai "Explain quantum computing in 3 sentences"

# Pipe input
cat error.log | ai-cli openai "What went wrong?"
echo "package main" | ai-cli groq "Complete this Go program"

# Interactive chat
ai-cli ollama -i

Usage

ai-cli <provider> [flags] [prompt]

Flags

Default Provider

ai-cli default set openai --model gpt-4o
ai-cli "Hello, world"    # uses OpenAI with gpt-4o
ai-cli default show
ai-cli default clear

Conversations

Sessions auto-save in interactive mode. Manage them with:

ai-cli chat list                        # List saved sessions
ai-cli chat show <id>                   # Display a conversation
ai-cli chat continue <id>              # Resume where you left off
ai-cli chat export <id>                # Export as markdown
ai-cli chat export <id> -f json        # Export as JSON
ai-cli chat delete <id>                # Delete a session

Sessions are stored as JSONL in ~/.local/share/ai-cli/sessions/.

JSON Output

ai-cli ollama --output json "What is Go?" | jq .response

{
  "provider": "Ollama",
  "model": "deepseek-r1:1.5b",
  "prompt": "What is Go?",
  "response": "Go is a statically typed...",
  "error": null
}

Shell Completions

# Bash
source <(ai-cli completion bash)

# Zsh
ai-cli completion zsh > "${fpath[1]}/_ai-cli"

# Fish
ai-cli completion fish | source

Model names complete dynamically: ai-cli ollama --model <TAB>.

Configuration

Config is stored in ~/.config/ai-cli/config.yaml:

active_provider: openai
providers:
  openai:
    base_url: https://api.openai.com/v1
    model: gpt-4o
  ollama:
    model: llama3.1

Settings merge with CLI flags (explicit flags always win). Environment variables with the AI_CLI_ prefix override config values.

Architecture

cmd/ai-cli/main.go            Entrypoint — signal handling, context setup
internal/
├── cli/                       Cobra commands, chat loop, session management
├── api/                       HTTP client with auth headers, friendly errors
├── config/                    YAML config via Viper, XDG paths, JSON migration
├── provider/                  Interface, self-registering registry, error types
│   ├── ollama/                Ollama native API (/api/chat)
│   ├── openaicompat/          Shared OpenAI-compatible SSE streaming client
│   ├── openai/                OpenAI (thin wrapper)
│   ├── groq/                  Groq (thin wrapper)
│   ├── localai/               LocalAI (thin wrapper)
│   └── custom/                Custom endpoint (thin wrapper)
├── session/                   JSONL conversation persistence
├── render/                    Glamour markdown rendering
├── prompt/                    System prompt constants
└── loader/                    TTY-aware terminal spinner (stderr)

Providers self-register via init(). Adding a new provider is four steps — see CONTRIBUTING.md.

Development

make build      # Build binary (version injected via ldflags)
make test       # Tests with race detector
make format     # go fmt + go vet
make clean      # Remove artifacts

See CONTRIBUTING.md for the full guide.

License

MIT