1# ask - AI CLI tool
  2
  3A lightweight bash script for querying AI models via the OpenRouter API, optimized for direct, executable output.
  4
  5## Quick start
  6
  7```bash
  8# Clone and setup
  9git clone https://github.com/yourusername/ask.git
 10cd ask
 11chmod +x ask
 12
 13# Set your API key
 14export OPENROUTER_API_KEY="your-api-key-here"
 15
 16# Test it
 17./ask remove lines in file1 that appear in file2
 18
 19grep -vFf file2 file1 > file3 && mv file3 file1
 20
 21[inception/mercury-coder via Inception - 0.86s - 20.9 tok/s]
 22```
 23
 24## Installation
 25
 26### Option 1: Using install.sh 
 27```bash
 28sudo ./install.sh
 29```
 30
 31### Option 2: Manual installation
 32```bash
 33chmod +x ask
 34sudo cp ask /usr/local/bin/
 35```
 36
 37### Persistent API key setup
 38
 39Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
 40```bash
 41export OPENROUTER_API_KEY="your-api-key-here"
 42```
 43
 44## Usage
 45
 46### Basic usage
 47
 48```bash
 49ask "What is 2+2?"
 50ask "Write a Python hello world"
 51```
 52
 53### Model selection
 54
 55```bash
 56# Default model (Mercury Coder - optimized for code)
 57ask "Write a Python function"
 58
 59# Shorthand flags for quick model switching
 60ask -c "prompt"  # Mercury Coder (default, best for code)
 61ask -g "prompt"  # Gemini 2.5 Flash (fast, general purpose)
 62ask -s "prompt"  # Claude Sonnet 4 (complex reasoning)
 63ask -k "prompt"  # Kimi K2 (long context)
 64ask -q "prompt"  # Qwen 235B (large model)
 65
 66# Custom model by full name
 67ask -m "openai/gpt-4o" "Explain this concept"
 68```
 69
 70### Provider routing
 71
 72Specify provider order for fallback support:
 73
 74```bash
 75ask --provider "cerebras,together" "Generate code"
 76```
 77
 78This will try Cerebras first, then fall back to Together if needed.
 79
 80### System prompts
 81
 82```bash
 83# Custom system prompt
 84ask --system "You are a pirate" "Tell me about sailing"
 85
 86# Disable system prompt for raw model behavior
 87ask -r "What is 2+2?"
 88```
 89
 90### Streaming mode
 91
 92Get responses as they're generated:
 93
 94```bash
 95ask --stream "Tell me a long story"
 96```
 97
 98### Pipe input
 99
100```bash
101echo "Fix this code: print('hello world)" | ask
102cat script.py | ask "Review this code"
103```
104
105## Options
106
107| Option | Description |
108|--------|-------------|
109| `-c` | Use Mercury Coder (default) |
110| `-g` | Use Google Gemini 2.5 Flash |
111| `-s` | Use Claude Sonnet 4 |
112| `-k` | Use Moonshotai Kimi K2 |
113| `-q` | Use Qwen3 235B |
114| `-m MODEL` | Use custom model |
115| `-r` | Disable system prompt |
116| `--stream` | Enable streaming output |
117| `--system` | Set custom system prompt |
118| `--provider` | Set provider order (comma-separated) |
119| `-h, --help` | Show help message |
120
121## Common use cases
122
123### Command generation
124```bash
125# Get executable commands directly
126ask "Command to find files larger than 100MB"
127# Output: find . -type f -size +100M
128
129ask "ffmpeg command to convert mp4 to gif"
130# Output: ffmpeg -i input.mp4 -vf "fps=10,scale=320:-1:flags=lanczos" output.gif
131```
132
133### Code generation
134```bash
135# Generate code snippets
136ask "Python function to calculate factorial"
137
138# Code review
139cat script.py | ask "Find potential bugs in this code"
140```
141
142### Quick answers
143```bash
144# Calculations
145ask "What is 18% of 2450?"
146# Output: 441
147
148# Technical questions
149ask "What port does PostgreSQL use?"
150# Output: 5432
151```
152
153### Advanced usage
154```bash
155# Chain commands
156ask "List all Python files" | ask "Generate a script to check syntax of these files"
157
158# Use with other tools
159docker ps -a | ask "Which containers are using the most memory?"
160
161```
162
163## Requirements
164
165### Dependencies
166- `bash` - Shell interpreter
167- `curl` - HTTP requests to OpenRouter API
168- `jq` - JSON parsing for API responses
169- `bc` - Performance metrics calculation
170
171### API access
172- OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai))
173- Set as environment variable: `OPENROUTER_API_KEY`
174
175### Missing dependencies
176```bash
177# Check for required tools
178which curl jq bc
179
180# Install on macOS
181brew install jq bc
182
183# Install on Ubuntu/Debian
184sudo apt-get install jq bc
185```
186
187### No response or errors
188```bash
189# Test with verbose curl output
190curl -v https://openrouter.ai/api/v1/chat/completions \
191  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
192  -H "Content-Type: application/json" \
193  -d '{"model":"google/gemini-2.5-flash","messages":[{"role":"user","content":"test"}]}'
194```
195
196## License
197
198MIT