ShellAI (s)

Convert plain English into shell commands — powered by AI.

$ s "find all files larger than 100MB"

  ╭─ Command ──────────────────────────────╮
  │  find . -size +100M                    │
  ╰────────────────────────────────────────╯

  Explains  Finds all files larger than 100MB in the current directory

  Alternatives:
    • find . -size +100M -type f
    • du -ah . | sort -rh | head -20

  Run it? › [y] run   [n] cancel   [c] copy

Install

# Clone and install globally
cd shellAi
npm install
npm run build
npm link

# After install, run setup
s --setup

Or install from npm (once published):

npm install -g shellai
s --setup

Setup

Run the interactive setup to configure your API key:

s --setup

You'll be prompted to:

1. Choose your LLM provider (Groq or OpenAI)
2. Enter your API key
3. Set shell preferences

Getting a Free Groq API Key

1. Go to console.groq.com
2. Sign up for a free account
3. Navigate to API Keys in the sidebar
4. Click Create API Key
5. Copy the key and paste it during s --setup

Groq provides free access to Llama 3.3 70B — it's fast and works great for command generation.

Switching to OpenAI

If you prefer to use OpenAI:

s --setup
# Select "OpenAI (gpt-4o-mini)" as your provider
# Enter your OpenAI API key

Usage Examples

# Find large files
s "find all files larger than 100MB"

# Kill a process by port
s "kill the process running on port 3000"

# Compress a folder
s "compress this folder into a zip"

# Disk usage
s "show disk usage sorted by size"

# Git operations
s "undo the last commit but keep the changes"

How It Works

1. You type a command description in plain English
2. ShellAI detects your OS, shell, and working directory
3. It sends your request to an LLM (Groq or OpenAI) with full context
4. The LLM returns a precise shell command with an explanation
5. You choose to run, cancel, or copy the command

Safety Features

• Dangerous command warnings: Commands that delete or modify files are flagged with a red warning
• Double confirmation for rm -rf: Extra safety for destructive deletions
• Sudo detection: Yellow warning when commands require elevated privileges
• No auto-sudo: Commands never include sudo unless you explicitly ask

Configuration

Config is stored at ~/.shellai/config.json:

{
  "groqApiKey": "gsk_...",
  "openaiApiKey": "",
  "defaultProvider": "groq",
  "shell": "auto",
  "confirmBeforeRun": true
}

View your current config:

s --config

Commands

| Command | Description | |---------|-------------| | s "your request" | Convert English to a shell command | | s --setup | Configure API keys and preferences | | s --config | Show current configuration | | s --help | Show help information | | s --version | Show version number |

Tech Stack

• TypeScript + Node.js 18+
• Groq API (primary, free) — Llama 3.3 70B
• OpenAI API (fallback) — GPT-4o-mini
• Commander — CLI argument parsing
• Inquirer — Interactive prompts
• Chalk — Colored terminal output
• Ora — Loading spinners
• Execa — Safe command execution
• Clipboardy — Clipboard support

License

MIT