mashell 0.1.2

AI-powered command line assistant - any model, anywhere

MaShell

███╗   ███╗ █████╗ ███████╗██╗  ██╗███████╗██╗     ██╗     
████╗ ████║██╔══██╗██╔════╝██║  ██║██╔════╝██║     ██║     
██╔████╔██║███████║███████╗███████║█████╗  ██║     ██║     
██║╚██╔╝██║██╔══██║╚════██║██╔══██║██╔══╝  ██║     ██║     
██║ ╚═╝ ██║██║  ██║███████║██║  ██║███████╗███████╗███████╗
╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝

🐚 Your AI-Powered Command Line Assistant

MaShell is an AI agent that lives in your terminal. It can run commands, write code, create projects, and accomplish complex tasks — all through natural conversation.

---

⚡ Quick Start

# Install (macOS/Linux)
pipx install mashell

# Or with pip (in a virtual environment)
pip install mashell

# Run (first time will guide you through setup)
mashell

Note: On macOS, we recommend pipx for installing CLI tools. Install it with brew install pipx if you don't have it.

That's it! MaShell will walk you through connecting to your AI provider (OpenAI, Azure, Anthropic, or local Ollama).

---

🎬 See It In Action

Example 1: Find the Largest Video File

You: find biggest video file on my computer

💭 I'll check common video locations first...

▶ Run:
  $ du -sh ~/Documents ~/Downloads ~/Desktop ~/Movies

📋 Output:
342G    /Users/jacob/Documents
5.4G    /Users/jacob/Downloads
4.8G    /Users/jacob/Desktop
12K     /Users/jacob/Movies

💭 Documents is huge. Let me search for videos there...

▶ Run:
  $ find ~/Documents -type f \( -iname "*.mp4" -o -iname "*.mkv" \) -exec ls -lhS {} + | head -10

📋 Output:
-rw-r--r--  3.8G  Peaky Blinders S06E06.mkv
-rw-r--r--  3.7G  The.Brutalist.2024.mp4
-rw-r--r--  3.0G  Mission.Impossible.mkv
...

MaShell: Found it! The biggest video is:
**3.8G** — ~/Documents/Bitcomet/Peaky Blinders S06E06.mkv

Example 2: Build a Project From Scratch

You: create a python project that can scrape web pages

💭 I'll set up a proper Python project structure...

▶ Run:
  $ mkdir -p python-scraper/{src,tests,outputs}
✓ Done

▶ Run:
  $ cat << 'EOF' > python-scraper/src/fetch.py
  import httpx
  def fetch(url): ...
  EOF
✓ Done

... (creates requirements.txt, README, .gitignore, venv, installs deps)

▶ Run:
  $ ./run.sh scrape https://example.com
📋 Output:
URL: https://example.com
Status: 200
Title: Example Domain

MaShell: Done! Created a Python web scraper at ./python-scraper

Try it: ./run.sh scrape https://example.com --out outputs/page.html

Example 3: Scrape a Website

You: use it to scrape www.cnn.com and see what's happening today

▶ Run:
  $ ./run.sh scrape https://www.cnn.com --out outputs/cnn.html
📋 Output:
Status: 200
Title: Breaking News, Latest News and Videos | CNN
Saved: outputs/cnn.html

💭 Let me extract the headlines...

▶ Run:
  $ python -c "from bs4 import BeautifulSoup; ..."

MaShell: Today's top story: "Trump ramps up rhetoric on ICE despite calls for de-escalation"

---

🔧 Setup Options

Option 1: Interactive Setup (Recommended)

Just run mashell — if no config exists, it will guide you:

🐚 MaShell Configuration Wizard

Step 1: Choose your LLM provider
  1. openai    - OpenAI API (GPT-4o, etc.)
  2. azure     - Azure OpenAI Service
  3. anthropic - Anthropic API (Claude)
  4. ollama    - Local Ollama (no API key needed)

Select provider: 2

Step 2: API Endpoint URL
Enter your Azure OpenAI endpoint: https://your-resource.openai.azure.com/

Step 3: API Key
Enter your API key: ********

Step 4: Model / Deployment Name
Deployment name: gpt-4o

✅ Configuration saved!

Option 2: Command Line Arguments

# OpenAI
mashell --provider openai --url https://api.openai.com/v1 --key sk-... --model gpt-4o "your task"

# Azure OpenAI
mashell --provider azure --url https://your-resource.openai.azure.com --key xxx --model gpt-4o "your task"

# Anthropic
mashell --provider anthropic --url https://api.anthropic.com --key sk-ant-... --model claude-sonnet-4-20250514 "your task"

# Local Ollama (no key needed)
mashell --provider ollama --url http://localhost:11434 --model llama3 "your task"

Option 3: Environment Variables

export MASHELL_PROVIDER="openai"
export MASHELL_URL="https://api.openai.com/v1"
export MASHELL_KEY="sk-..."
export MASHELL_MODEL="gpt-4o"

mashell "your task"

---

🎯 What Can MaShell Do?

Task	Example
Find files	"find the largest video on my computer"
Create projects	"build a Python web scraper from scratch"
Run code	"run this script and fix any errors"
Git operations	"commit all changes with a good message"
Install tools	"install ffmpeg and convert video.mp4 to gif"
System tasks	"clean up files older than 30 days in Downloads"
Debug	"why is my Python script failing?"
Explore	"what's taking up space on my disk?"

---

🔐 Permission System

MaShell always asks before running commands:

╭─────────────────── 🔐 Permission Request ───────────────────╮
│                                                              │
│  Tool: shell                                                 │
│                                                              │
│  Command:                                                    │
│  $ rm -rf ./node_modules                                     │
│                                                              │
╰──────────────────────────────────────────────────────────────╯
   Approve   Deny   Edit   Always approve this session
Choice [y/n/e/a]: 

• y — Run this command
• n — Block it
• e — Edit the command first
• A — Auto-approve all commands this session (use with caution!)

---

💡 Tips

1. Be specific — "find large files" → "find video files larger than 1GB in Downloads"

2. Let it explore — MaShell thinks step-by-step like a human, checking results before deciding what to do next

3. Auto-approve mode — Use mashell -y "task" for trusted, quick tasks

4. Interactive mode — Just run mashell to chat back and forth

---

📦 Installation from Source

git clone https://github.com/anthropics/MaShell.git
cd MaShell
pip install -e .

For development:

python -m mashell "your task"

---

📄 License

GPL-3.0 — Free to use, modify, and share.

---

Built for developers who live in the terminal 🐚