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:

On startup, Magic Shell checks saved built-in model IDs against the model catalog shipped with the installed version. If an update removes or disables your default model, Magic Shell selects an enabled default from the same provider and saves the corrected ID. Valid selections and custom models are preserved.

{
  "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 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.