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/kagisearch/ask.git
 10cd ask
 11
 12chmod +x ask
 13sudo cp ask /usr/local/bin/
 14
 15
 16# Make sure you have you OpenRouter API key
 17export OPENROUTER_API_KEY="your-api-key-here"
 18
 19# Test it
 20> ask remove lines in file1 that appear in file2
 21
 22grep -vFf file2 file1 > file3 && mv file3 file1
 23
 24[inception/mercury-coder via Inception - 0.66s - 20.9 tok/s]
 25```
 26
 27We also provide a handy install script.
 28
 29## Usage
 30
 31### Basic usage
 32
 33```bash
 34ask ffmpeg command to convert mp4 to gif
 35```
 36
 37### Model selection
 38
 39```bash
 40# Default model (Mercury Coder - optimized for code)
 41ask find files larger than 20mb
 42
 43# Shorthand flags for quick model switching
 44ask -c "prompt"  # Mercury Coder (default, best for code)
 45ask -g "prompt"  # Gemini 2.5 Flash (fast, general purpose)
 46ask -s "prompt"  # Claude Sonnet 4 (complex reasoning)
 47ask -k "prompt"  # Kimi K2 (long context)
 48ask -q "prompt"  # Qwen 235B (large model)
 49
 50# Custom model by full name
 51ask -m "openai/gpt-4o" "Explain this concept"
 52```
 53
 54### Provider routing
 55
 56Specify provider order for fallback support:
 57
 58```bash
 59ask --provider "cerebras,together" "Generate code"
 60```
 61
 62This will try Cerebras first, then fall back to Together if needed.
 63
 64### System prompts
 65
 66```bash
 67# Custom system prompt
 68ask --system "You are a pirate" "Tell me about sailing"
 69
 70# Disable system prompt for raw model behavior
 71ask -r "What is 2+2?"
 72```
 73
 74### Streaming mode
 75
 76Get responses as they're generated:
 77
 78```bash
 79ask --stream "Tell me a long story"
 80```
 81
 82### Pipe input
 83
 84```bash
 85echo "Fix this code: print('hello world)" | ask
 86cat script.py | ask "Review this code"
 87```
 88
 89## Options
 90
 91| Option | Description |
 92|--------|-------------|
 93| `-c` | Use Mercury Coder (default) |
 94| `-g` | Use Google Gemini 2.5 Flash |
 95| `-s` | Use Claude Sonnet 4 |
 96| `-k` | Use Moonshotai Kimi K2 |
 97| `-q` | Use Qwen3 235B |
 98| `-m MODEL` | Use custom model |
 99| `-r` | Disable system prompt |
100| `--stream` | Enable streaming output |
101| `--system` | Set custom system prompt |
102| `--provider` | Set provider order (comma-separated) |
103| `-h, --help` | Show help message |
104
105## Common use cases
106
107### Command generation
108```bash
109# Get executable commands directly
110ask "Command to find files larger than 100MB"
111# Output: find . -type f -size +100M
112
113ask "ffmpeg command to convert mp4 to gif"
114# Output: ffmpeg -i input.mp4 -vf "fps=10,scale=320:-1:flags=lanczos" output.gif
115```
116
117### Code generation
118```bash
119# Generate code snippets
120ask "Python function to calculate factorial"
121
122# Code review
123cat script.py | ask "Find potential bugs in this code"
124```
125
126### Quick answers
127```bash
128# Calculations
129ask "What is 18% of 2450?"
130# Output: 441
131
132# Technical questions
133ask "What port does PostgreSQL use?"
134# Output: 5432
135```
136
137### Advanced usage
138```bash
139# Chain commands
140ask "List all Python files" | ask "Generate a script to check syntax of these files"
141
142# Use with other tools
143docker ps -a | ask "Which containers are using the most memory?"
144
145```
146
147## Requirements
148
149### Dependencies
150- `bash` - Shell interpreter
151- `curl` - HTTP requests to OpenRouter API
152- `jq` - JSON parsing for API responses
153- `bc` - Performance metrics calculation
154
155### API access
156- OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai))
157- Set as environment variable: `OPENROUTER_API_KEY`
158
159## License
160
161MIT