@austinthesing/magic-shell

v0.2.22

Published

4 days ago

Natural language to terminal commands with safety features. Supports OpenCode Zen, OpenRouter, AI gateways, Workers AI, and custom models.

0High
0Medium
0Low

austinthesing

cli terminal natural-language shell ai openrouter opencode zen command-line nlp gpt claude llm

Magic Shell

Transform natural language into terminal commands with built-in safety features.

Magic Shell is an open-source CLI tool that translates plain English (or any natural language) into shell commands using AI. It supports multiple AI providers, includes a beautiful interactive TUI mode, and features a comprehensive safety system to protect you from dangerous commands.

Features

Natural Language Translation: Describe what you want to do in plain English
Multiple AI Providers: OpenCode Zen (with free models!), OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Workers AI, and custom models (LM Studio, Ollama, OpenAI-compatible)
Custom Model Support: Add your own local or remote models with secure API key storage
Project Context Aware: Opt-in detection of package.json scripts, Makefile targets, etc.
Interactive TUI Mode: Full-featured terminal interface with themes
Command Safety Analysis: Multi-level safety checks before executing commands
Auto Updates: Automatic update checking with one-command upgrades
Cross-Platform: macOS, Linux, and Windows support
Shell-Aware: Automatically detects and adapts to your shell (bash, zsh, fish, PowerShell, etc.)
Secure Credential Storage: Uses system keychain (macOS Keychain, Linux secret-tool, Windows Credential Manager)
Command History: Context-aware translations based on your recent commands
Beautiful Themes: 8 built-in themes including Tokyo Night, Catppuccin, Dracula, and more

Installation

Via Package Manager (Recommended)

Prerequisite: Magic Shell runs on the Bun runtime. Install Bun first, even if you install the package with npm, pnpm, or yarn.

# bun (recommended)
bun add -g @austinthesing/magic-shell

# npm
npm install -g @austinthesing/magic-shell

# pnpm
pnpm add -g @austinthesing/magic-shell

# yarn
yarn global add @austinthesing/magic-shell

From Source

Prerequisite: Bun runtime (v1.3.9 or higher)

# Clone the repository
git clone https://github.com/austin-thesing/magic-shell.git
cd magic-shell

# Install dependencies
bun install

# Build
bun run build

# Link globally (optional)
bun link

Quick Start

# Run setup to configure your API key
msh --setup

# Or set via environment variable
export OPENCODE_ZEN_API_KEY="your-key-here"

Usage

Use msh for CLI mode and mshell for TUI mode.

Basic Commands

# Translate a query to a command (prints the command)
msh "list all javascript files"
# Output: find . -name "*.js"

# Translate and execute
msh -x "show disk usage"

# Dry run - preview with safety analysis
msh -n "delete all node_modules folders"

# Launch interactive TUI mode
mshell

Command Reference

| Command | Description | ------------------------- | msh <query> | msh -x <query> | msh -n <query> | mshell | msh --setup | msh --models | msh --model <id> | msh --add-model | msh --list-custom | msh --remove-model | msh --provider <name> | msh --thinking <level> | msh --themes | msh --theme <name> | msh --repo-context | msh -r <query> | msh --version | msh --check-update | msh --help | | ------------------------------------------- | | Translate query to command and print it | | Translate and execute the command | | Dry run - show command with safety analysis | | Launch interactive TUI mode | | Configure API keys and provider | | List available models | | Set default model (including custom models) | | Add custom model (LM Studio, Ollama, etc.) | | List custom models | <id> | Remove custom model | | Set provider (OpenCode Zen, OpenRouter, gateways, Workers AI, or custom) | | Set thinking level (off, low, medium, high) | | List available themes | | Set color theme | | Enable project context detection | | Use project context for single query | | Show version | | Check for updates | | Show help |

Examples

# File operations
msh "find all files larger than 100MB"
msh "count lines of code in this project"
msh "show the 10 most recently modified files"

# Git operations
msh "undo my last commit but keep changes"
msh "show commits from the last week"
msh "create a branch from main called feature-login"

# System operations
msh "check which process is using port 3000"
msh "show memory usage"
msh "list all running docker containers"

# Execute directly
msh -x "show current git branch"

# Pipe to clipboard (macOS)
msh "compress this folder to a zip file" | pbcopy

Interactive TUI Mode

Launch with mshell for a full interactive experience.

Keyboard Shortcuts

All shortcuts use the Ctrl+X chord (press Ctrl+X, then the key):

| Shortcut | Action | | ---------- | ---------------------- | | Ctrl+X P | Open command palette | | Ctrl+X M | Change model | | Ctrl+X S | Switch provider | | Ctrl+X D | Toggle dry-run mode | | Ctrl+X T | Change theme | | Ctrl+X R | Toggle project context | | Ctrl+X H | Show history | | Ctrl+X C | Show config | | Ctrl+X L | Clear output | | Ctrl+X ? | Show help | | Ctrl+X Q | Exit | | Ctrl+C | Exit / Cancel | | Esc | Close dialogs |

Direct Commands in TUI

You can also type commands directly in the TUI:

!help or /help - Show help
!model or /model - Change model
!provider or /provider - Switch provider
!dry or /dry - Toggle dry-run mode
!config or /config - Show current configuration
!history or /history - Show command history
!clear or /clear - Clear output

Note: Both ! and / prefixes work for all commands. Use whichever feels more natural!

AI Providers

OpenCode Zen (Recommended)

OpenCode Zen provides curated models optimized for coding tasks, including free models.

Free Models:

deepseek-v4-flash-free - DeepSeek's free fast open-source model (default)
mimo-v2.5-free - Xiaomi's free long-context MiMo model
north-mini-code-free - North's free coding model
nemotron-3-ultra-free - NVIDIA Nemotron free trial model
big-pickle - OpenCode stealth model
gpt-5-nano - OpenAI's free lightweight GPT model

Premium Models:

Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5, Claude Fable 5
Kimi K2.6
DeepSeek V4 Pro, DeepSeek V4 Flash
GLM 5.2, GLM 5.1
Qwen3.7 Max, Qwen3.7 Plus
MiMo V2.5, MiMo V2.5 Pro
MiniMax M2.7
Gemini 3.5 Flash, Gemini 3.1 Pro, Gemini 3 Flash
GPT 5.5, GPT 5.5 Pro, GPT 5.4 Mini/Nano, GPT 5.3 Codex
And more...

Get your API key at: https://opencode.ai/auth

OpenRouter

Access to a wide variety of models from different providers.

Open-source and open-weight highlights:

Kimi K2.7 Code, Kimi K2.6
DeepSeek V4 Pro, DeepSeek V4 Flash
GLM 5.2, GLM 5.1, GLM 5 Turbo
Qwen3.7 Max, Qwen3.7 Plus
MiniMax M3, MiniMax M2.7
MiMo V2.5, MiMo V2.5 Pro
And many more...

Get your API key at: https://openrouter.ai/keys

Custom Models

Magic Shell supports custom models for local or remote OpenAI-compatible endpoints, including:

LM Studio - Run models locally
Ollama - Local model management
Any OpenAI-compatible API - Self-hosted or third-party endpoints

Adding a Custom Model:

# Interactive setup
msh --add-model

# You'll be prompted for:
# - Model ID (for referencing, e.g., "my-local-llama")
# - Display name (e.g., "Local Llama 3.2")
# - API model ID (sent to server, e.g., "llama-3.2-3b")
# - Base URL (e.g., "http://localhost:1234/v1")
# - API key (optional, stored securely in keychain)
# - Category (fast/smart/reasoning)

Managing Custom Models:

# List all custom models
msh --list-custom

# Set a custom model as default
msh --model my-local-llama

# Remove a custom model
msh --remove-model my-local-llama

Custom model API keys are securely stored in your system keychain, just like provider API keys.

Safety System

Magic Shell includes a comprehensive safety analysis system that categorizes commands by risk level:

Severity Levels

| Level | Description | Examples | | ------------ | -------------------------------------- | --------------------------------------- | | Critical | Could cause irreversible system damage | rm -rf /, fork bombs, disk overwrites | | High | Significant changes or data loss risk | sudo rm, kill -9 -1, shutdown | | Medium | Requires elevated privileges | sudo, chmod, package removal | | Low | Worth reviewing | git checkout, npm install |

Safety Levels

Configure your preferred safety level:

Strict: Confirm all potentially risky commands
Moderate (default): Confirm high and critical severity commands
Relaxed: Only confirm critical severity commands

Blocked Commands

Certain dangerous patterns are always blocked:

Fork bombs
Direct disk writes (> /dev/sda)
Filesystem formatting (mkfs)
Recursive permission changes on root (chmod -R 777 /)

Configuration

Configuration is stored in ~/.magic-shell/config.json.

Config Options

{
  "provider": "opencode-zen",
  "defaultModel": "deepseek-v4-flash-free",
  "thinkingLevel": "low",
  "safetyLevel": "moderate",
  "dryRunByDefault": false,
  "repoContext": false,
  "theme": "opencode",
  "blockedCommands": [...],
  "confirmedDangerousPatterns": [...],
  "customModels": [
    {
      "id": "my-local-llama",
      "name": "Local Llama 3.2",
      "modelId": "llama-3.2-3b",
      "baseUrl": "http://localhost:1234/v1",
      "contextLength": 128000,
      "category": "smart"
    }
  ]
}

Environment Variables

| Variable | Description | | -------------------------------- | ----------------------------------- | | OPENCODE_ZEN_API_KEY | API key for OpenCode Zen | | OPENROUTER_API_KEY | API key for OpenRouter | | AI_GATEWAY_API_KEY | API key for Vercel AI Gateway | | CLOUDFLARE_AI_GATEWAY_API_KEY | API key/token for Cloudflare Gateway | | CLOUDFLARE_API_TOKEN | API token for Workers AI | | CLOUDFLARE_ACCOUNT_ID | Account ID for Cloudflare providers | | CLOUDFLARE_AI_GATEWAY_ID | Gateway ID for Cloudflare Gateway | | DEBUG_API=1 | Enable API response debugging |

Themes

Magic Shell includes 8 beautiful themes:

opencode (default) - Orange and blue tones
tokyonight - Soft purple and blue
catppuccin - Pastel Mocha variant
gruvbox - Retro warm tones
nord - Arctic cool blues
dracula - Purple vampire vibes
one-dark - Atom-inspired
matrix - Classic green terminal

Change themes:

# CLI
msh --theme tokyonight

# TUI
Ctrl+X T

Shell Support

Magic Shell automatically detects and adapts to your shell:

Bash - Full support with bash-specific syntax
Zsh - Extended globbing and array syntax
Fish - Fish-specific syntax (no $(), different variable syntax)
PowerShell / pwsh - Cmdlet syntax and object pipelines
CMD - Windows command syntax
Nushell - Structured data syntax
POSIX sh - Portable fallback

Platform Support

| Platform | Shell Detection | Keychain Storage | | -------- | --------------- | ----------------------- | | macOS | Full | macOS Keychain | | Linux | Full | libsecret (secret-tool) | | Windows | Full | Credential Manager | | WSL | Full (detected) | libsecret |

Development

# Run in development mode
bun run dev

# Run TUI in development mode
bun run dev:tui

# Type check
bun run typecheck

# Build for distribution
bun run build

Project Structure

src/
  index.ts          # CLI entry point
  cli.ts            # TUI mode
  lib/
    types.ts        # Type definitions and model configs
    config.ts       # Configuration management
    api.ts          # AI provider integrations
    safety.ts       # Command safety analysis
    theme.ts        # Theme system
    keychain.ts     # Secure credential storage
    shell.ts        # Shell/platform detection

Publishing to npm

Prerequisites

Create an npm account at https://www.npmjs.com/signup
Login to npm:
```
npm login
```

Preparing for Release

Update package.json - Ensure these fields are set correctly:

{
  "name": "@austinthesing/magic-shell",
  "version": "0.2.13",
  "description": "Natural language to terminal commands with safety features",
  "main": "dist/index.js",
  "bin": {
    "msh": "dist/index.js",
    "mshell": "dist/tui.js"
  },
  "files": ["dist", "README.md", "LICENSE"],
  "repository": {
    "type": "git",
    "url": "https://github.com/austin-thesing/magic-shell.git"
  },
  "homepage": "https://github.com/austin-thesing/magic-shell#readme",
  "bugs": {
    "url": "https://github.com/austin-thesing/magic-shell/issues"
  },
  "keywords": ["cli", "terminal", "natural-language", "shell", "ai", "openrouter", "opencode", "command-line"],
  "author": "Your Name <[email protected]>",
  "license": "MIT"
}

Build the project:
```
bun run build
```

Test locally before publishing:

# Create a tarball
npm pack

# Install it globally to test
npm install -g ./magic-shell-0.1.0.tgz

# Test it works
msh --help

# Uninstall test version
npm uninstall -g magic-shell

Publishing

# Publish to npm (first time)
npm publish

# Publish with public access (for scoped packages like @your-username/magic-shell)
npm publish --access public

Releasing New Versions

Update version (follows semver):

# Patch release (bug fixes): 0.1.0 -> 0.1.1
npm version patch

# Minor release (new features): 0.1.0 -> 0.2.0
npm version minor

# Major release (breaking changes): 0.1.0 -> 1.0.0
npm version major

Push tags to GitHub:
```
git push origin main --tags
```
Publish the new version:
```
npm publish
```

Automated Releases with GitHub Actions

Create .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install

      - name: Build
        run: bun run build

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true

Add your npm token to GitHub:

Generate token at https://www.npmjs.com/settings/tokens (use "Automation" type)
Add to repository secrets as NPM_TOKEN

Version Management Tips

Use npm version commands - they automatically:
- Update package.json version
- Create a git commit
- Create a git tag
Consider using Changesets for monorepo or complex versioning

Add a prepublishOnly script to ensure builds are fresh:

{
  "scripts": {
    "prepublishOnly": "bun run build"
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE for details.

Release Notes

v0.2.22 - Model Catalog and Release Prep

Refreshed OpenCode Zen and OpenRouter model registries with current June 2026 open-source/open-weight entries
Updated the default free Zen model to deepseek-v4-flash-free
Added Zen routing support for Qwen models on the Messages endpoint
Updated release docs and website provider surfaces for the refreshed provider/model set

v0.2.20 - Thinking Controls and Zen Free Models

Added --thinking <level> and thinkingLevel config support (off, low, medium, high)
Added provider-specific reasoning controls for supported OpenRouter, OpenCode Zen, gateway, and custom models
Updated OpenCode Zen free models and default model references to minimax-m2.5-free
Disabled custom thinking parameters when the selected model/provider does not support them

v0.2.19 - AI Gateway Providers

Added Vercel AI Gateway, Cloudflare AI Gateway, and Cloudflare Workers AI providers
Added gateway provider setup, switching, model listing, API-key handling, and environment variables
Refreshed OpenCode Zen and OpenRouter registries with current OpenAI, Anthropic, Kimi, DeepSeek, GLM, MiniMax, and MiMo model IDs
Added provider-scoped model helpers so model selection follows the active provider

v0.2.18 - Model Registry Refresh

Added latest MiMo V2.5 and MiMo V2.5 Pro entries for OpenCode Zen
Added latest Xiaomi MiMo V2.5 and MiMo V2.5 Pro entries for OpenRouter
Removed the older OpenRouter MiMo V2 Flash free entry from docs and model listings
Updated runtime dependencies for the published CLI package

v0.2.17 - Dependency Maintenance

Updated published CLI dependencies to current releases
Fixed TUI input typing compatibility after the @opentui/core upgrade

v0.2.15 - Slash Command Support

Added / command support in TUI mode (e.g., /help, /clear)
Both ! and / prefixes now work for all TUI commands
Updated help text to show command options

v0.2.14

Improved CI/CD workflows
Enhanced landing page SEO and structure
Fixed bin paths in package.json

v0.2.13

Added custom model support (LM Studio, Ollama, OpenAI-compatible)
Secure credential storage via system keychain
Project context detection for package.json scripts and Makefile
Multiple AI providers (OpenCode Zen, OpenRouter)
Beautiful TUI with 8 built-in themes
Comprehensive safety system with severity levels

Acknowledgments

Built with Bun
TUI powered by @opentui/core
Theme colors inspired by OpenCode

Magic Shell - Type what you mean, execute what you need.