Configuration

API Key Setup

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

msh --setup

This will guide you through:

Selecting a provider (OpenCode Zen or OpenRouter)
Entering your API key
Choosing a default model

Get an API Key

OpenCode Zen (Recommended)
OpenRouter

OpenCode Zen offers curated models optimized for coding, including free models.

Visit opencode.ai/auth
Create an account or sign in
Copy your API key

Environment Variables

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.

Configuration File

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

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

Options

Option	Description	Default
`provider`	AI provider (`opencode-zen` or `openrouter`)	`opencode-zen`
`defaultModel`	Default model ID	`big-pickle`
`safetyLevel`	Safety strictness (`strict`, `moderate`, `relaxed`)	`moderate`
`dryRunByDefault`	Always show commands without executing	`false`
`theme`	Color theme name	`opencode`

Secure Key Storage

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

Platform	Storage Location
macOS	macOS Keychain
Linux	libsecret (secret-tool)
Windows	Windows Credential Manager

Changing Settings

Via CLI

# Change provider
msh --provider openrouter

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

# Change theme
msh --theme tokyonight

# List available models
msh --models

# List available themes
msh --themes

Via TUI

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

Debug Mode

Enable API response debugging:

DEBUG_API=1 msh "your query"

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