Magic Shell is an open-source CLI tool that translates natural language into shell commands using AI. It supports multiple AI providers (OpenCode Zen with free models, OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Workers AI, and custom models), includes a beautiful interactive TUI mode, and features comprehensive safety analysis to protect against dangerous commands.

Is Magic Shell free to use?

Yes, Magic Shell is completely free and open-source under the MIT license. It supports free AI models through OpenCode Zen (including deepseek-v4-flash-free, mimo-v2.5-free, north-mini-code-free, nemotron-3-ultra-free, big-pickle, and gpt-5-nano) as well as premium models from various providers. You can also use custom local models with LM Studio or Ollama at no cost.

What AI providers does Magic Shell support?

Magic Shell supports OpenCode Zen (recommended, with free models), OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Workers AI, and custom OpenAI-compatible endpoints. You can also add custom models from LM Studio, Ollama, or any OpenAI-compatible API. Each provider offers different models with varying capabilities and pricing.

How does the safety system work?

Magic Shell analyzes every command for potential risks before execution. Commands are categorized into severity levels (low, medium, high, critical). Critical commands like 'rm -rf /' or fork bombs are always blocked. You can configure safety levels: strict (confirm all risky commands), moderate (confirm high severity), or relaxed (minimal confirmations). The system uses pattern matching, privilege detection, and path analysis to identify dangerous operations.

What's the difference between msh and mshell commands?

msh is the quick CLI mode for one-shot command translations. Use it like 'msh "find large files"' to get a command, or 'msh -x "show disk usage"' to execute directly. mshell launches the full interactive TUI mode with themes, command history, model switching, and keyboard shortcuts. TUI mode is recommended for extended sessions and exploration.

Can I use Magic Shell with local AI models?

Yes! Magic Shell supports custom models from LM Studio, Ollama, or any OpenAI-compatible endpoint. Run 'msh --add-model' to configure a custom model with your local server URL. This allows you to use Magic Shell completely offline with locally-hosted models.

What platforms does Magic Shell support?

Magic Shell works on macOS, Linux, and Windows. It automatically detects your shell (bash, zsh, fish, PowerShell, CMD, Nushell, or POSIX sh) and adapts command syntax accordingly. Credentials are securely stored using your system's native keychain (macOS Keychain, Linux libsecret, or Windows Credential Manager).

How do I switch between different AI models?

In CLI mode, use 'msh --model ' to set the default model. In TUI mode, press Ctrl+X M or type /models to switch models. Typing / opens a slash command menu, and you can also switch providers with 'msh --provider ' or by using Ctrl+P and choosing Switch Provider in TUI mode. Run 'msh --models' to see all available models.

What are the keyboard shortcuts in TUI mode?

Magic Shell follows OpenCode-style TUI shortcuts where they fit: Ctrl+P opens Commands, Ctrl+X M changes model, Ctrl+X T changes theme, Ctrl+X Q exits, Ctrl+T cycles thinking level, Ctrl+C exits or cancels the active dialog first, Ctrl+D exits, and Esc closes dialogs.

Open Source CLI Tool

Talk to your terminal.In plain English.

Turn plain English into the right terminal command—analyzed for safety before it ever runs.

Get Started GitHub

terminal

magic-shell

deepseek-v4-flash-free

Provider: opencode-zenModel: deepseek-v4-flash-free Safe Mode

Command:

Low risk

>Auto-executed (safe command)

Enter ExecuteCtrl+P Commands/ Slash menu

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

$npm install -g @austinthesing/magic-shell@latest

$pnpm add -g @austinthesing/magic-shell@latest

01 — Capabilities

Magic Shell 1.0 is here

Unified palettes, slash commands, explicit safety, and faster model switching—so you stop memorizing flags and just type.

Natural Language

Describe what you want in plain English. Get the right command for your shell—no man-page digging required.

Safety Analysis

Every command is checked for risk before it runs. Destructive patterns are blocked automatically—so a typo won't cost you.

Multiple AI Providers

Pick from OpenCode Zen, OpenRouter, Vercel and Cloudflare gateways, Workers AI, or your own local models. Free options on every provider.

Unified Palettes

Commands, slash actions, models, providers, themes, safety, and thinking levels share one picker. Learn it once, use it everywhere.

Slash Commands

Type / to discover actions. /models, /providers, /themes, /safety, and /thinking open the same pickers as the keyboard shortcuts—no menus to hunt.

Project Aware

Opt-in context detection reads your package.json scripts, Makefile targets, and more. Say 'run dev'—it already knows what to do.

Shell-Aware

Detects bash, zsh, fish, PowerShell, and more automatically. Every command adapts to your shell's syntax—no guesswork.

Auto Updates

Checks for new versions on startup and can install them for you. Stay current without thinking about it.

02 — Two modes

Two ways to use

A full TUI when you want it, a one-liner when you don't.

[]

Interactive TUI

Recommended

A full terminal interface with unified command palettes, slash commands, themes, history, model switching, and safety analysis.

launch

$ mshell

8 beautiful themes
Command history
Switch models and providers on the fly
Slash commands and keyboard shortcuts

Quick CLI

One-shot commands for fast translations. Pipe output, use in scripts, or execute directly with -x.

examples

$ msh "find large files" find . -type f -size +100M $ msh -x "show disk usage"

Quick one-liners
Pipe to clipboard
Script-friendly
Dry-run with -n

03 — Safety

Built-in safety

Every command is checked before it runs. The dangerous ones never reach your shell.

Low

low

Worth reviewing before running

$ git checkout main

Medium

medium

Requires elevated privileges

$ sudo apt install

High

high

Significant changes or data loss risk

$ rm -rf node_modules

Critical

critical

Blocked - could cause system damage

$ rm -rf /

04 — Themes

8 beautiful themes

Match your terminal aesthetic. Switch live with Ctrl+X T or /themes.

magic-shell

$msh "find large files"

find . -type f -size +100M

05 — Get started

Get started in seconds

One command to install—free models to start. Works on macOS, Linux, and Windows.

1
Install
$bun add -g @austinthesing/magic-shell@latest
$npm install -g @austinthesing/magic-shell@latest
$pnpm add -g @austinthesing/magic-shell@latest
2
Configure your API key
setup
$ msh --setup
3
Launch the TUI
launch
$ mshell

Read the docs Star on GitHub