Configuration

Magic Shell requires an API key from one of the supported providers. Run the setup wizard:

msh --setup

This will guide you through:

1. Selecting a provider (OpenCode Zen, OpenRouter, or custom models)
2. Entering your API key (if needed)
3. Choosing a default model

You can also set your API key via environment variables:

# OpenCode Zen
export OPENCODE_ZEN_API_KEY="your-key-here"

# OpenRouter
export OPENROUTER_API_KEY="your-key-here"

Add these to your shell profile (~/.bashrc, ~/.zshrc, etc.) for persistence.

Magic Shell supports custom models for local or remote OpenAI-compatible endpoints. This is perfect for running models locally with LM Studio or Ollama.

# Interactive setup wizard
msh --add-model

The wizard will prompt you for:

• Model ID (unique identifier)
• Display name
• API model ID (sent to the server)
• Base URL (e.g., http://localhost:1234/v1)
• API key (optional, stored securely)
• Category (fast/smart/reasoning)

# List all custom models
msh --list-custom

# Set a custom model as default
msh --model my-local-llama

# Remove a custom model
msh --remove-model my-local-llama

Custom model API keys are stored securely in your system keychain, just like provider API keys.

Magic Shell stores configuration in ~/.magic-shell/config.json:

{
  "provider": "opencode-zen",
  "defaultModel": "big-pickle",
  "safetyLevel": "moderate",
  "dryRunByDefault": false,
  "theme": "opencode"
}

API keys are stored securely in your system’s keychain:

# Change provider
msh --provider openrouter

# Change default model
msh --model claude-3-5-sonnet

# Add a custom model
msh --add-model

# List custom models
msh --list-custom

# Change theme
msh --theme tokyonight

# List available models
msh --models

# List available themes
msh --themes

In TUI mode (mshell), use keyboard shortcuts:

• Ctrl+X M - Change model
• Ctrl+X S - Switch provider
• Ctrl+X T - Change theme
• Ctrl+X C - View config

Enable API response debugging:

DEBUG_API=1 msh "your query"

This shows the full API request and response, useful for troubleshooting.