_
  __ _ ___| | __
 / _` / __| |/ /
| (_| \__ \   <
 \__,_|___/_|\_\

Natural language to shell commands, powered by local AI.

A CLI tool that translates what you mean into what to type, using Ollama models running entirely on your machine.

• Runs 100% locally — No API keys, no cloud, no data leaves your machine
• Project-aware — Detects Go, Node, Python, Rust, and tailors commands accordingly
• Explain mode — Don't know what a command does? Ask ?tar -czf
• Safety warnings — Flags dangerous commands like rm -rf before execution
• Interactive REPL — Conversational shell with command history context
• Usage statistics — Track your usage with --stats

curl -fsSL https://raw.githubusercontent.com/ykushch/ask/main/install.sh | bash

This will:

• Install Ollama if not already present
• Pull the default model (qwen2.5-coder:7b)
• Install the ask binary to ~/.local/bin

curl -fsSL https://raw.githubusercontent.com/ykushch/ask/main/uninstall.sh | bash

ask find all markdown files in this directory
# → find . -name "*.md" [Enter to run]

ask show disk usage sorted by size
# → du -sh * | sort -h [Enter to run]

ask kill the process on port 3000
# → lsof -t -i:3000 | xargs kill [Enter to run]

ask

Drops into a REPL where you can type queries continuously:

projects > list go files
→ find . -name "*.go" [Enter to run]
projects > compress the src folder
→ tar -czf src.tar.gz src [Enter to run]

Interactive commands:

• !help — show available commands
• !model NAME — switch model
• !model — show current model
• !explain CMD — explain a shell command
• ?CMD — explain a shell command (shorthand)
• ? — explain the last executed command
• !cmd — run cmd directly (bypass AI)
• Ctrl+D — exit

Don't know what a command does? Ask for an explanation:

ask --explain "find . -name '*.go' -exec grep 'func main' {} +"
# Finds all .go files in the current directory tree and searches each one for lines containing "func main".
#   -name '*.go': match files ending in .go
#   -exec grep 'func main' {} +: run grep on the matched files

Also works in interactive mode with the ? prefix:

projects > ?tar -czf src.tar.gz src
# Compresses the src directory into a gzipped tar archive named src.tar.gz.
#   -c: create a new archive
#   -z: compress with gzip
#   -f src.tar.gz: name the output file

Commands are tailored to your project type. ask detects signature files in the current directory:

Dangerous commands are flagged with a warning before execution:

  ⚠ Warning: Recursive deletion targeting a broad path
→ rm -rf ~/Documents [Enter to run]

Detected patterns include rm -rf, dd, mkfs, chmod 777, git push --force, DROP TABLE, and more. Warnings are informational — you can still press Enter to proceed.

# Via flag
ask --model llama3 show my public ip

# Via environment variable
export ASK_MODEL=deepseek-r1
ask list running docker containers

ask --update

Self-updates the binary to the latest GitHub release. A background version check also runs on every invocation — if a newer version is available, you'll see a notice after the command completes.

ask -v
# ask version 0.1.0
# model: qwen2.5-coder:7b
# ollama: http://localhost:11434

Track how you use ask over time:

ask --stats
# ask usage statistics
# ────────────────────
# Total invocations:     150
# Commands generated:    120
# Commands executed:      95  (79%)
# Explain calls:          15
# Interactive sessions:   20
# One-shot commands:     100
#
# Model usage:
#   qwen2.5-coder:7b    140  (93%)
#   llama3               10  (7%)
#
# Stats file: ~/.ask/stats.json (12KB)
# Tracking since: 2026-01-29

Statistics are stored locally in ~/.ask/stats.json.

The default model is qwen2.5-coder:7b — a good balance of speed and accuracy for shell command generation. Depending on your hardware and needs, you may want to try other models:

Tips:

• For most users, the default qwen2.5-coder:7b works well
• On machines with limited RAM (<8 GB), try nemotron-mini (2.7 GB) or deepseek-coder:6.7b (3.8 GB)
• For complex commands requiring step-by-step reasoning, nemotron-3-nano or deepseek-r1 may produce better results (requires 32 GB+ RAM)

Switch models with --model or set ASK_MODEL:

ask --model nemotron-mini show disk usage
# or
export ASK_MODEL=nemotron-mini

• macOS or Linux
• Ollama (installed automatically by the install script)

git clone https://github.com/ykushch/ask.git
cd ask
go build -o ask .

# Set up git hooks (runs tests on commit)
make setup

# Run tests
make test