Configuration

API Key Setup

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

msh --setup

The setup wizard guides you through:

1. Selecting a provider: OpenCode Zen, OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Workers AI, or custom models.
2. Entering your API key.
3. Choosing a default model.

Keys stored in the system keychain through msh --setup take precedence over environment variables.

Custom Models

Magic Shell supports local or remote OpenAI-compatible endpoints, including LM Studio and Ollama.

msh --add-model

The wizard prompts for:

• Model ID
• Display name
• API model ID
• Base URL
• Optional API key
• Category: fast, smart, or reasoning

Manage custom models from the CLI:

msh --list-custom
msh --model my-local-llama
msh --remove-model my-local-llama

Config File

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

{
  "provider": "opencode-zen",
  "defaultModel": "deepseek-v4-flash-free",
  "safetyLevel": "moderate",
  "dryRunByDefault": false,
  "theme": "opencode"
}

Key	Description	Default
provider	AI provider	opencode-zen
defaultModel	Default model ID	deepseek-v4-flash-free
safetyLevel	Safety strictness: strict, moderate, or relaxed	moderate
dryRunByDefault	Always show commands without executing	false
theme	Color theme name	opencode

CLI Configuration

msh --provider openrouter
msh --model claude-sonnet-4-6
msh --theme tokyonight
msh --models
msh --themes

TUI Configuration

In TUI mode (mshell), use the v1.0 palettes:

• Ctrl+P opens the command palette.
• / opens slash commands from the prompt.
• Ctrl+X M or /models opens the model picker.
• Ctrl+X T or /themes opens the theme picker.
• Ctrl+Y or /safety opens the safety picker.
• Ctrl+T or /thinking opens the thinking picker.
• Esc and Ctrl+C close the active modal.

Debug Mode

Enable API response debugging:

DEBUG_API=1 msh "your query"

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