# 🧙 ShellSage > AI-powered shell command assistant — describe what you want, get the exact command. ``` ___ _ _ _ ___ / __| |_ ___| | / __| __ _ __ _ ___ \__ \ ' \/ -_) | \__ \/ _` / _` / -_) |___/_||_\___|_|_|___/\__,_\__, \___| |___/ ``` **Stack:** Python · Groq (llama3-70b) · Netlify Functions · Neon Postgres (all free) --- ## Features | Feature | Description | |---|---| | 🔮 Generate | Natural language → shell command with full breakdown | | 🔍 Explain | Dissect any command token by token | | 🔧 Fix | Paste a broken command + error, get it fixed | | ✏️ Refine | Tweak the last command interactively | | ▶️ Run | Execute generated commands directly from the CLI | | 📋 Copy | One-keypress clipboard copy | | 🗂️ History | Persistent history synced to Postgres | | 🔎 Search | Search history by keyword | | 💻 REPL | Interactive mode — just run `shellsage` | | 🎨 TUI | Cyberpunk Rich UI — panels, spinners, color themes | | ⚠️ Danger | Strict danger detection — warns on destructive commands | | 🐚 Shell-aware | macOS / Linux / zsh / bash / fish | --- ## Setup ### 1. Get free API keys **Groq** (AI — free): 1. Go to [console.groq.com](https://console.groq.com) 2. Sign up → API Keys → Create API Key 3. Copy it **Neon** (Postgres — free): 1. Go to [neon.tech](https://neon.tech) 2. Sign up → New Project → any name 3. Dashboard → Connection string → copy `postgresql://...` --- ### 2. Deploy backend to Netlify 1. Push this repo to GitHub (only the `netlify/` folder needs to be in the repo root or set base dir) 2. Go to [netlify.com](https://netlify.com) → **Add new site → Import from GitHub** 3. Select your repo 4. Set build settings: - **Base directory:** `netlify` - **Build command:** *(leave empty)* - **Publish directory:** `netlify` - **Functions directory:** `netlify/functions` 5. Click **Deploy site** 6. Go to **Site → Environment variables** → Add: - `GROQ_API_KEY` = your Groq key - `DATABASE_URL` = your Neon connection string 7. **Deploys → Trigger deploy → Deploy site** to redeploy with env vars --- ### 3. Install the CLI ```bash cd shellsage/cli pip install -e . ``` ### 4. Point CLI at your Netlify URL ```bash shellsage config --set api_url=https://YOUR-SITE.netlify.app ``` --- ## Usage ```bash # Interactive REPL (recommended) shellsage # Generate a command shellsage "find all .log files older than 7 days and delete them" # Explain a command shellsage --explain "find . -name '*.log' -mtime +7 -delete" # Fix a broken command shellsage --fix "grep -r TODO ." --fix-error "grep: invalid option" # Run immediately after generating shellsage "list all docker containers" --run # History shellsage --history shellsage --search "docker" shellsage --clear-history ``` ### Interactive REPL commands | Input | Action | |---|---| | `` | Generate a command | | `refine: make it recursive` | Refine the last command | | `fix: ` | Fix the last command | | `explain: ` | Explain a command | | `search: ` | Search history | | `history` | Show recent commands | | `config` | Show config | | `clear` | Clear screen | | `?` / `help` | Show help | | `exit` / `quit` | Exit | ### After each command ``` [c] copy [r] run [q] back ``` --- ## Config ```bash shellsage config --set api_url=https://your-site.netlify.app shellsage config --set shell=zsh shellsage config --set history_sync=true ``` Stored at `~/.shellsage/config.json` --- ## Project Structure ``` shellsage/ ├── cli/ │ ├── shellsage/ │ │ ├── __init__.py │ │ ├── main.py # CLI entry + REPL │ │ ├── api.py # Netlify API client │ │ ├── ui.py # Rich TUI │ │ ├── config.py # ~/.shellsage/config.json │ │ ├── clipboard.py # Cross-platform clipboard │ │ └── runner.py # Shell executor │ └── pyproject.toml ├── netlify/ │ ├── functions/ │ │ ├── command.py # POST /api/command │ │ ├── explain.py # POST /api/explain │ │ ├── fix.py # POST /api/fix │ │ ├── refine.py # POST /api/refine │ │ ├── history.py # GET/POST/DELETE /api/history │ │ └── requirements.txt │ └── netlify.toml └── README.md ``` --- ## Requirements - Python 3.10+ - `rich`, `requests` (auto-installed) - Netlify free account - Neon free account - Groq free API key --- ## License MIT # ShellSage