Stop memorizing. Start talking.
Whisper CLI is your natural language terminal assistant. Forget arcane flags, obscure syntax, and Stack Overflow searches—just type what you want in plain English, and Whisper translates it into the exact shell command you need.
whisper> show me all files modified today
→ find . -mtime 0
whisper> what's using port 8080
→ lsof -ti:8080
whisper> kill that process
→ kill 12345Safe commands run automatically. Risky ones ask first.
- 🗣️ Natural Language Interface: Type what you want in plain English
- ⚡ Smart & Safe: Auto-runs safe commands, asks before anything risky
- 💬 Remembers Context: Ask follow-up questions naturally
- 🎨 Beautiful Terminal UI: Clean, color-coded output
- 🚀 Works Both Ways: Use natural language OR type shell commands directly
- Install and run:
npm install -g @shahidrogers/whisper-cli
whisper-
On first launch, enter your OpenRouter API key (get one free at https://openrouter.ai/)
-
Start typing what you want:
whisper> show me all files
→ ls -la
whisper> what's using port 8080
→ lsof -ti:8080
whisper> find all .log files modified today
→ find . -name "*.log" -mtime 0
Whisper CLI classifies every command into three risk levels:
Read-only commands that can't harm your system:
- File viewing:
ls,cat,head,tail,grep,find - Process inspection:
ps,lsof,netstat - Git read operations:
git status,git diff,git log - System info:
pwd,whoami,hostname,date
Commands that modify state or require user approval:
- File mutations:
rm,mv,cp,chmod - Process control:
kill,killall - Package managers:
npm,pip,brew - Commands with redirection or chaining:
>,&&,|| - Unknown commands
Note: Simple read-only pipes like ps aux | grep node remain SAFE and auto-execute.
Highly destructive commands blocked by default:
sudocommands (ALWAYS blocked, even with /arm)rm -rf(recursive deletion)git reset --hard- Commands touching sensitive paths (
/etc,~/.ssh,/var) - System utilities:
dd,mkfs,format
Whisper remembers your recent conversation, so you can ask follow-up questions naturally:
whisper> list apps running on port 3000
→ lsof -i :3000
whisper> port 4000?
→ lsof -i :4000
whisper> kill it
→ kill 12345
Use /clear when you want to start fresh.
If you already know the exact command, just type it. Whisper runs it directly without using AI:
whisper> ls -la
→ ls -la
whisper> git status
→ git status
This is faster and saves API calls. The cd command even changes Whisper's working directory, so you can navigate naturally:
whisper> cd ~/projects
✓ Changed directory to /Users/you/projects
whisper> pwd
→ /Users/you/projects
Control Whisper CLI behavior with meta commands:
| Command | Description |
|---|---|
/help |
Show help message |
/exit |
Quit (also Ctrl+D) |
/dry |
Toggle dry-run mode (preview without executing) |
/models |
List all available models (interactive picker in TTY) |
/model <id> |
Change LLM model (e.g., /model xiaomi/mimo-v2-flash:free) |
/key |
Change your OpenRouter API key |
/history |
Interactive history browser with search (arrow keys, Enter for details, ESC to exit) |
/clear |
Clear conversation history and screen |
/arm |
Enable dangerous commands for 60 seconds |
/unarm |
Disable arm mode immediately |
Keyboard shortcuts: Tab for autocomplete, ESC to cancel while thinking, Ctrl+U/K to clear input, arrows for suggestions.
Your settings live at ~/.config/whisper/config.json. Change them with meta commands like /model or edit the file directly.
{
"api_key": "sk-or-...",
"selected_model": "xiaomi/mimo-v2-flash:free",
"default_model": "xiaomi/mimo-v2-flash:free",
"fallback_model": "mistralai/devstral-2512:free",
"auto_run_safe": true,
"max_output_lines": 300,
"command_timeout_ms": 10000,
"arm_duration_seconds": 60,
"custom_denylist": [],
"custom_allowlist": [],
"first_run_complete": false
}The api_key is set on first launch. Change it anytime with /key.
The default free model works great for most commands. If you want to try others, use /models to see the list:
Free options: MiMo-V2-Flash (default), Devstral 2 Paid options: Claude, Gemini, DeepSeek, and more
Switch anytime with /models for an interactive picker.
Add custom safety rules to your config:
{
"custom_denylist": ["docker", "kubectl"],
"custom_allowlist": ["mycompanytool"]
}Every command you run is logged to ~/.local/share/whisper/log.jsonl for accountability. Use /history to browse past commands interactively.
whisper> show me all files
→ ls -la
whisper> find all Python files in this directory
→ find . -name "*.py"
whisper> show me the last 50 lines of error.log
→ tail -n 50 error.log
whisper> what's using port 8080
→ lsof -ti:8080
whisper> show all node processes
→ ps aux | grep node
whisper> kill process 1234
[CAUTION] kill 1234
Send SIGTERM to process 1234
Proceed? (y/n) [default: n]
whisper> show me recent commits
→ git log --oneline -10
whisper> what files changed in the last commit
→ git show --name-only HEAD
whisper> show uncommitted changes
→ git diff
whisper> how much disk space is free
→ df -h
whisper> what's my IP address
→ ifconfig | grep "inet "
whisper> show system uptime
→ uptime
Whisper CLI analyzes commands for dangerous patterns:
- Redirection operators (
>,>>) - Command chaining (
;,&&,||) - Subshells (
$(...),`...`) - Sensitive paths (
/etc,/var,~/.ssh,/usr,/bin) - Dangerous patterns (
rm -rf,git reset --hard,dd,mkfs)
Smart Pipe Detection: Whisper recognizes safe command pipelines and won't block legitimate patterns:
# SAFE - Read-only command piped to safe filters
ps aux | grep node
cat error.log | tail -n 100 | grep ERROR
find . -name "*.js" | wc -l
# CAUTION - Includes redirection or mutations
ps aux | grep node > output.txt # File redirection requires confirmation
git add . && git commit -m "msg" # Chaining requires confirmation
# DANGEROUS - Blocked without /arm
rm -rf ./temp && echo "done"
sudo apt-get install nginxWhy the distinction?
- Pipes to filters (
grep,awk,sort,head,tail, etc.) are purely read-only transformations → SAFE - Redirection (
>) writes to files → Could overwrite important data → CAUTION - Chaining (
&&,;) could link an innocent command with a dangerous one → CAUTION - Destructive commands → DANGEROUS (requires /arm)
This means the LLM can naturally generate pipes and chains - they're not blocked, just reviewed when they involve mutations or redirection.
For dangerous operations, use /arm to enable for 60 seconds:
whisper> /arm
⚠ Dangerous commands enabled for 60 seconds
whisper> delete temp directory
[DANGEROUS] rm -rf ./temp
Recursively delete temp directory
Proceed? (y/n) [default: n] y
Preview commands without executing:
whisper> /dry
Dry-run mode enabled
whisper> delete all log files
[DRY RUN] Would execute: rm *.log
sudo commands are ALWAYS blocked, regardless of arm mode, for security:
whisper> install nginx
✗ Blocked: sudo commands are always blocked for safety
Use /key in Whisper, or set the OPENROUTER_API_KEY environment variable.
The LLM couldn't generate a valid JSON response. This usually means:
- Your request is too ambiguous - try being more specific
- The model is struggling with JSON formatting - try
/modelsto switch to a different model - Your API key may be invalid or out of credits - check at https://openrouter.ai/
Tip: Use direct shell commands (e.g., ls -la) to bypass the LLM entirely when you know the exact command.
Increase timeout in config:
{
"command_timeout_ms": 30000
}Use custom allowlist:
{
"custom_allowlist": ["mytool"]
}MIT License - see LICENSE file for details.
- Report bugs: GitHub Issues
- Discussions: GitHub Discussions