GitHub - kagisearch/ask: A lightweight bash script for querying AI models via the OpenRouter API, optimized for direct, executable output.

ask - AI CLI tool

A lightweight bash script for querying AI models via the OpenRouter API, optimized for direct, executable output.

Quick start

# Clone and setup
git clone https://github.com/kagisearch/ask.git
cd ask

chmod +x ask
sudo cp ask /usr/local/bin/


# Make sure you have you OpenRouter API key
export OPENROUTER_API_KEY="your-api-key-here"

# Test it
> ask remove lines in file1 that appear in file2

grep -vFf file2 file1 > file3 && mv file3 file1

[inception/mercury-coder via Inception - 0.66s - 20.9 tok/s]

We also provide a handy install script.

Usage

Basic usage

ask ffmpeg command to convert mp4 to gif

Model selection

# Default model (Mercury Coder - optimized for code)
ask find files larger than 20mb

# Shorthand flags for quick model switching
ask -c "prompt"  # Mercury Coder (default, best for code)
ask -g "prompt"  # Gemini 2.5 Flash (fast, general purpose)
ask -s "prompt"  # Claude Sonnet 4 (complex reasoning)
ask -k "prompt"  # Kimi K2 (long context)
ask -q "prompt"  # Qwen 235B (large model)

# Custom model by full name
ask -m "openai/gpt-4o" "Explain this concept"

Provider routing

Specify provider order for fallback support:

ask --provider "cerebras,together" "Generate code"

This will try Cerebras first, then fall back to Together if needed.

System prompts

# Custom system prompt
ask --system "You are a pirate" "Tell me about sailing"

# Disable system prompt for raw model behavior
ask -r "What is 2+2?"

Streaming mode

Get responses as they're generated:

ask --stream "Tell me a long story"

Pipe input

echo "Fix this code: print('hello world)" | ask
cat script.py | ask "Review this code"

Options

Option	Description
`-c`	Use Mercury Coder (default)
`-g`	Use Google Gemini 2.5 Flash
`-s`	Use Claude Sonnet 4
`-k`	Use Moonshotai Kimi K2
`-q`	Use Qwen3 235B
`-m MODEL`	Use custom model
`-r`	Disable system prompt
`--stream`	Enable streaming output
`--system`	Set custom system prompt
`--provider`	Set provider order (comma-separated)
`-h, --help`	Show help message

Common use cases

Command generation

# Get executable commands directly
ask "Command to find files larger than 100MB"
# Output: find . -type f -size +100M

ask "ffmpeg command to convert mp4 to gif"
# Output: ffmpeg -i input.mp4 -vf "fps=10,scale=320:-1:flags=lanczos" output.gif

Code generation

# Generate code snippets
ask "Python function to calculate factorial"

# Code review
cat script.py | ask "Find potential bugs in this code"

Quick answers

# Calculations
ask "What is 18% of 2450?"
# Output: 441

# Technical questions
ask "What port does PostgreSQL use?"
# Output: 5432

Advanced usage

# Chain commands
ask "List all Python files" | ask "Generate a script to check syntax of these files"

# Use with other tools
docker ps -a | ask "Which containers are using the most memory?"

Requirements

Dependencies

bash - Shell interpreter
curl - HTTP requests to OpenRouter API
jq - JSON parsing for API responses
bc - Performance metrics calculation

API access

OpenRouter API key (get one at openrouter.ai)
Set as environment variable: OPENROUTER_API_KEY

License

MIT