Installation

Complete guide to installing and configuring Calliope CLI.

Requirements

Node.js 18 or later
npm (included with Node.js)
Terminal - Works on macOS, Linux, Windows (WSL recommended)

Installation Methods

Global Installation (Recommended)

Install globally to use from any directory:

npm install -g @calliopelabs/cli

Verify the installation:

calliope --help

Using npx (No Install)

Run directly without installing:

npx @calliopelabs/cli

This downloads and runs the latest version each time.

Local Installation

Install in a specific project:

npm install @calliopelabs/cli
npx calliope

First-Time Setup

When you run calliope for the first time, you’ll be guided through setup:

1. Select Provider

Choose your preferred AI provider:

? Select AI provider:
  ❯ Anthropic (Claude)
    OpenAI (GPT)
    Google (Gemini)
    Mistral
    Groq
    Together
    OpenRouter
    Ollama (local)

2. Enter API Key

Enter your API key for the selected provider:

? Enter your Anthropic API key: sk-ant-api...

The key is stored securely in your config file.

3. Choose Persona

Select your preferred interaction style:

? Select persona:
  ❯ calliope    - Poetic and creative
    professional - Clear and concise
    minimal     - Extremely brief

Configuration

Config File Location

Configuration is stored at platform-specific locations:

Platform	Location
macOS	`~/.config/calliope/config.json`
Linux	`~/.config/calliope/config.json`
Windows	`%APPDATA%\calliope\config.json`

View your config path:

calliope --config

Command-Line Options

Option	Description
`-h`, `--help`	Show help information
`-v`, `--version`	Show version number
`--config`	Show config file location
`--reset`	Reset configuration to defaults
`--setup`, `--configure`	Force setup wizard
`--skip-setup`	Skip setup if API keys in environment
`-g`, `--god-mode`	Run without permission prompts
`-a`, `--agterm`	Enable multi-agent orchestration mode
`--legacy`	Use legacy readline UI instead of Ink

Reset Configuration

To start fresh:

calliope --reset

This clears all stored API keys and settings.

Environment Variables

You can configure Calliope entirely through environment variables:

# Primary providers
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...

# Additional providers
export MISTRAL_API_KEY=...
export GROQ_API_KEY=...
export TOGETHER_API_KEY=...
export OPENROUTER_API_KEY=...
export AI21_API_KEY=...
export HUGGINGFACE_API_KEY=...

# Self-hosted services
export OLLAMA_BASE_URL=http://localhost:11434
export LITELLM_BASE_URL=http://localhost:4000
export LITELLM_API_KEY=...

Environment variables take precedence over config file values.

Updating

Update to the latest version:

npm update -g @calliopelabs/cli

Check your current version:

calliope --version

Uninstalling

Remove Calliope CLI:

npm uninstall -g @calliopelabs/cli

To also remove configuration:

# macOS/Linux
rm -rf ~/.config/calliope

# Windows
rmdir /s %APPDATA%\calliope

Troubleshooting

“Command not found”

Ensure npm global binaries are in your PATH:

# Check npm bin directory
npm config get prefix

# Add to PATH (bash/zsh)
export PATH="$(npm config get prefix)/bin:$PATH"

“Permission denied”

On Linux/macOS, if you get permission errors:

# Option 1: Use a Node version manager (recommended)
nvm install --lts
nvm use --lts
npm install -g @calliopelabs/cli

# Option 2: Change npm prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @calliopelabs/cli

“API key too short”

API keys have minimum length requirements. Ensure you copied the complete key including any prefixes like sk-ant-.

“Empty response from API”

Check your API key is valid
Verify you have credits/quota with the provider
Try a different provider with /provider <name>

Bring Your Own Keys