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