Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Installation

Prerequisites

  • OpenRouter API Key - Get one at https://openrouter.ai/keys
    • Already have API keys for OpenAI, Anthropic, or Google? Use OpenRouter's BYOK (Bring Your Own Key) feature to route requests through your existing accounts without additional payment processing through OpenRouter.
  • Rust (optional, only for building from source)

Installation Methods

Method 1: Pre-built Binary (Recommended)

Download the latest release for your platform from GitHub Releases.

Method 2: Cargo Install

cargo install zo-cli

Method 3: Build from Source

# Clone the repository
git clone https://github.com/svent/zo.git
cd zo
 
# Build release binary
cargo build --release
 
# Install
sudo cp target/release/zo /usr/local/bin/

Setup

1. Get OpenRouter API Key

  1. Visit https://openrouter.ai/keys
  2. Sign up or log in
  3. Create a new API key
  4. Copy the key (starts with sk-or-v1-)
💡 Tip: Already have OpenAI, Anthropic, or Google API keys?

You can use OpenRouter's BYOK (Bring Your Own Key) feature to use your existing provider keys instead of adding funds to OpenRouter. This lets you use zo as an LLM router without payment processing through OpenRouter:

  1. Go to https://openrouter.ai/settings/keys
  2. Add your existing provider API keys (OpenAI, Anthropic, Google, etc.)
  3. OpenRouter will route requests through your accounts
  4. You'll be billed directly by your providers

2. Configure API Key

You have two options:

Option A: Environment Variable (Recommended)

# Set for current session
export OPENROUTER_API_KEY="sk-or-v1-..."
 
# Make it persistent (add to ~/.bashrc or ~/.zshrc)
echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.bashrc
source ~/.bashrc

Option B: Configuration File

# Initialize config file
zo +init-config
 
# Edit the config file
vi ~/.config/zo/config.toml
 
# Add your API key
api_key = "sk-or-v1-..."

3. Verify Installation

# Test with a simple query
zo 'What is Rust?'
 
# Should see a streaming response

Configuration

Initialize Config File

zo +init-config

This creates ~/.config/zo/config.toml with helpful comments and examples.

Config File Location

  • Linux/macOS: ~/.config/zo/config.toml

Basic Configuration

# API Key (alternatively use OPENROUTER_API_KEY env var)
api_key = "sk-or-v1-..."
 
# Default model (uses fuzzy matching)
default_model = "flash"
 
# Syntax highlighting theme for code blocks
theme = "base16-ocean.dark"
 
# Custom colors for inline markdown elements
[inline_colors]
heading = "cyan"
inline_code = "yellow"
emphasis = "white"

Advanced Configuration

See Configuration for details on:

  • Custom models with system prompts
  • Theme selection
  • Color customization

Troubleshooting

"API key not found"

Make sure you've set the API key via environment variable or config file:

# Check environment variable
echo $OPENROUTER_API_KEY
 
# Or check config file
cat ~/.config/zo/config.toml

"Model not found"

List available models:

zo +list-models

Use fuzzy matching - /son matches sonnet, /gpt matches gpt4, etc.

Permission Denied

Make sure the binary is executable:

chmod +x /usr/local/bin/zo

Command Not Found

Ensure /usr/local/bin is in your PATH:

echo $PATH
 
# Add to PATH if needed (in ~/.bashrc or ~/.zshrc)
export PATH="/usr/local/bin:$PATH"

Upgrading

Pre-built Binary

Download and replace the binary:

curl -L https://github.com/svent/zo/releases/latest/download/zo-linux-x86_64 -o zo
chmod +x zo
sudo mv zo /usr/local/bin/

Cargo Install

cargo install zo-cli --force

From Source

cd zo
git pull
cargo build --release
sudo cp target/release/zo /usr/local/bin/

Uninstallation

# Remove binary
sudo rm /usr/local/bin/zo
 
# Remove config (optional)
rm -rf ~/.config/zo
 
# Remove from shell config (if using environment variable)
# Edit ~/.bashrc or ~/.zshrc and remove OPENROUTER_API_KEY line

Next Steps