Configuration

Complete reference for Calliope CLI configuration options.

Configuration Methods

Calliope CLI can be configured through:

1. Environment variables (highest priority)
2. Config file (~/.config/calliope/config.json)
3. Setup wizard (interactive)
4. Slash commands (runtime)

Environment variables override config file values.

Config File

Location

View your config path:

calliope --config

Structure

{
  "setupComplete": true,
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "persona": "professional",
  "maxIterations": 25,
  "fancyOutput": true,
  "autoSaveHistory": true,
  "autoUpgrade": true,
  "anthropicApiKey": "sk-ant-...",
  "googleApiKey": "...",
  "openaiApiKey": "sk-...",
  "deepseekApiKey": "sk-...",
  "ollamaBaseUrl": "http://localhost:11434",
  "profiles": {
    "work": { "persona": "professional", "maxIterations": 50 },
    "quick": { "persona": "minimal", "maxIterations": 10 }
  },
  "activeProfile": "default"
}

Managing Config

View config path:

calliope --config

Reset to defaults:

calliope --reset

Run setup wizard:

calliope --setup

Environment Variables

API Keys

Service URLs

Example Shell Configuration

Bash (~/.bashrc):

# Calliope CLI configuration
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

Zsh (~/.zshrc):

# Calliope CLI configuration
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

Fish (~/.config/fish/config.fish):

# Calliope CLI configuration
set -x ANTHROPIC_API_KEY "sk-ant-..."
set -x OPENAI_API_KEY "sk-..."

Configuration Options

Provider Settings

Valid providers: anthropic, google, openai, together, openrouter, groq, fireworks, mistral, ollama, ai21, huggingface, deepseek, litellm, auto

Agent Settings

Valid personas:

• calliope - Poetic and creative
• professional - Clear and concise
• minimal - Extremely brief

Display Settings

Session Settings

Profile Settings

Configuration Profiles

Save and switch between different configuration sets:

Creating Profiles

calliope> /profile save work
Profile "work" saved

calliope> /profile save quick
Profile "quick" saved

Listing Profiles

calliope> /profile list
Available profiles:
  - work
  - quick
  - default (active)

Switching Profiles

calliope> /profile work
Switched to profile "work"

Deleting Profiles

calliope> /profile delete quick
Profile "quick" deleted

Profile Contents

Profiles store:

• Provider and model settings
• Persona selection
• Max iterations
• Any runtime settings

Project Configuration

Create a .calliope or .calliope.conf file in your project root:

project: MyProject
provider: anthropic
model: claude-sonnet-4
persona: professional
maxIterations: 25

[tech]
typescript
react
node

[conventions]
Use functional components
Prefer async/await
Write tests for new features

[ignore]
node_modules/
dist/
.env

[commands]
build: npm run build
test: npm test
lint: npm run lint

Sections

Storage Directories

Calliope stores data in ~/.calliope-cli/:

Runtime Configuration

Slash Commands

Change settings during a session:

# Change provider
calliope> /provider google

# Change model
calliope> /model gemini-1.5-pro

# Change persona
calliope> /persona minimal

# View current config
calliope> /status

Command-Line Flags

Configuration Validation

Schema Validation

The config file is validated on load:

Invalid values are replaced with defaults.

API Key Validation

API keys are validated when used:

• Minimum length: Most keys require 40+ characters
• Format: Checked for provider-specific prefixes (e.g., sk-ant- for Anthropic)

Best Practices

Security

1. Use environment variables for API keys in shared environments
2. Don’t commit config files to version control
3. Restrict permissions on config files:

   chmod 600 ~/.config/calliope/config.json

Organization

1. Keep keys in shell config for persistence:

   # ~/.bashrc
   export ANTHROPIC_API_KEY="..."

2. Use different profiles for different projects:

   # Project-specific
   source .env.local
   calliope

Team Usage

For team projects, document the expected environment variables:

# .env.example (committed to repo)
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=

Team members create their own .env.local (gitignored) with actual values.