Magic Shell

Transform natural language into terminal commands with AI-powered translation, built-in safety, and a polished v1.0 terminal UI.

Magic Shell is an open-source CLI that turns plain English into shell commands. Use msh for fast one-shot translations or mshell for the interactive TUI with command palettes, slash commands, model switching, themes, safety controls, and command history.

v1.0

Magic Shell 1.0 is focused on day-to-day terminal UX:

• Unified command palettes for commands, slash commands, models, providers, themes, safety, thinking level, onboarding, and API key setup.
• Slash commands now open the same picker actions as the command palette instead of submitting /models or /providers as plain text.
• Esc and Ctrl+C close active modals before exiting the app.
• Safety and thinking controls now open explicit pickers instead of blindly cycling values.
• Model and provider pickers use clearer descriptions and consistent category/cost labels.

Install

bun add -g @austinthesing/magic-shell@latest

Other package managers:

npm install -g @austinthesing/magic-shell@latest
pnpm add -g @austinthesing/magic-shell@latest
yarn global add @austinthesing/magic-shell@latest

From source:

git clone https://github.com/austin-thesing/magic-shell.git
cd magic-shell
bun install
bun run build
bun link

Quick Start

msh --setup
mshell

You can also provide API keys with environment variables:

export OPENCODE_ZEN_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"

CLI Usage

msh "list all javascript files"
msh -x "show disk usage"
msh -n "delete all node_modules folders"
msh -r "run the dev server"

Command	Description
msh <query>	Translate a natural-language query to a shell command
msh -x <query>	Translate and execute immediately
msh -n <query>	Dry run with safety analysis
msh -r <query>	Include project context for one query
mshell	Launch interactive TUI mode
msh --setup	Configure provider and API keys
msh --models	List available models
msh --model <id>	Set the default model
msh --provider <name>	Set the active provider
msh --safety <level>	Set safety level: strict, moderate, relaxed
msh --thinking <level>	Set thinking level: off, low, medium, high
msh --themes	List themes
msh --theme <name>	Set theme
msh --repo-context	Enable project context detection
msh --add-model	Add a custom OpenAI-compatible model
msh --list-custom	List custom models
msh --remove-model <id>	Remove a custom model

TUI Usage

Launch the interactive app:

mshell

Core shortcuts:

Shortcut	Action
Ctrl+P	Open the command palette
/	Open slash commands from the prompt
Ctrl+X M	Open model picker
Ctrl+X T	Open theme picker
Ctrl+Y	Open safety level picker
Ctrl+T	Open thinking level picker
Esc	Close the active modal
Ctrl+C	Close the active modal, then exit when no modal is open
Ctrl+D	Exit
Ctrl+X Q	Exit

Slash commands expose the same functionality as the command palette:

Command	Action
/models	Select model
/providers	Switch provider
/themes	Select theme
/safety	Select safety level
/thinking	Select thinking level
/dry	Toggle dry-run mode
/config	Show config
/history	Show history
/clear	Clear chat
/help	Show help
/exit	Exit

Legacy ! commands still work for compatibility.

Providers

Magic Shell supports:

• OpenCode Zen
• OpenRouter
• Vercel AI Gateway
• Cloudflare AI Gateway
• Cloudflare Workers AI
• Custom OpenAI-compatible endpoints like LM Studio and Ollama

OpenCode Zen is the recommended default and includes free models. Get an API key at opencode.ai/auth.

Development

bun install
bun run dev
bun run dev:tui
bun run typecheck
bun run build

No test framework is configured yet.

---

Built by Austin Thesing · A Design X Develop LLC project