Installation
Quick install (macOS / Linux)
Downloads the latest release binary, verifies the SHA256 checksum, and installs to ~/.local/bin.
Pin a specific version or change the install directory:
$ YAAK_INSTALL_DIR=/usr/local/bin curl -fsSL https://getyaak.ai/install.sh | bash
Homebrew (macOS / Linux)
Arch Linux (AUR)
Two packages are available on the AUR: yaak-cli builds from source and yaak-cli-bin installs the upstream prebuilt binary.
$ yay -S yaak-cli-bin
Nix / NixOS
yaak ships a flake under packaging/nix. On any flake-enabled system:
$ nix run github:hanneshapke/yaak -- --help
Debian / Ubuntu (.deb)
A .deb package is attached to each GitHub release. Download and install directly:
$ sudo dpkg -i yaak_0.1.3_amd64.deb
Includes bash, zsh and fish shell completions.
Scoop (Windows)
$ scoop install yaak
Cargo
Prebuilt binaries and .deb packages are also available on the GitHub Releases page for Linux (x86_64), macOS (x86_64, aarch64), and Windows (x86_64).
Configuration
yaak resolves settings in this priority order: CLI flags → environment variables → config file → defaults.
Interactive wizard
The fastest way to get started. Run yaak --config to pick a language, provider, model, and enter your API key.
Config file
Stored at ~/.config/yaak/config.toml. On macOS, ~/Library/Application Support/yaak/config.toml is also checked.
api_base = "https://api.openai.com/v1"
api_key = "sk-..."
model = "gpt-4o-mini"
language = "en" # en, de, es, fr, pt, zh, ja, ko
Environment variables
$ export YAAK_API_KEY="sk-..."
$ export YAAK_MODEL="gpt-4o-mini"
$ export YAAK_LANGUAGE="en" # optional: en, de, es, fr, pt, zh, ja, ko
Usage
Describe what you want in plain English. yaak sends it to your LLM, shows you the generated command, and lets you execute, copy, or abort.
Thinking ....
Command: find . -name "*.rs" -mtime -7
? What next?: Execute / Refine / Copy / Abort
Reverse / Explain mode
Pass --reverse or --explain to get a detailed, token-by-token breakdown of any command.
Copy to clipboard
Use --copy to send the generated command straight to your clipboard without executing.
Command history
yaak saves every generated command. Browse, search, or re-run from history.
$ yaak --last # re-execute the last command
$ yaak --search "docker" # search by keyword
Shell completions
$ yaak --completions zsh > ~/.zfunc/_yaak
$ yaak --completions fish > ~/.config/fish/completions/yaak.fish
All flags
| Flag | Short | Description |
|---|---|---|
--config | -c | Interactive configuration wizard |
--api-base | -u | API base URL |
--api-key | -k | API key |
--model | -m | Model name |
--yes | -y | Skip confirmation prompt |
--reverse | -r | Explain a command instead of generating |
--explain | -e | Alias for --reverse |
--copy | -C | Copy generated command to clipboard |
--context | Include project type and file listing in prompt | |
--cache | Reuse cached result (exact or BM25 fuzzy match) | |
--no-cache | Force fresh API call, ignore cache | |
--history | -H | Show recent command history |
--last | -l | Re-execute the most recent command |
--search | -s | Search command history by keyword |
--language | -L | UI language: en, de, es, fr, pt, zh, ja, ko |
--version | -v | Print version number |
--update | -U | Update yaak to the latest version |
--feedback | Open the feedback page in your browser | |
--completions | Generate shell completions (bash/zsh/fish) | |
--limit | Number of history entries to show (default: 20) |
Multi-language support
yaak supports 8 languages for all UI elements — prompts, error messages, menus, and labels. The configuration wizard includes a language selection step, or you can set it directly.
| Code | Language |
|---|---|
en | English |
de | Deutsch |
es | Español |
fr | Français |
pt | Português |
zh | 中文 (Chinese) |
ja | 日本語 (Japanese) |
ko | 한국어 (Korean) |
Setting the language
Language is resolved in priority order: CLI flag → environment variable → config file → system locale → English.
$ yaak -L de list files in current directory
# Environment variable
$ export YAAK_LANGUAGE=fr
# Config file (~/.config/yaak/config.toml)
language = "es"
# Or select during setup
$ yaak --config
LLM explanations
When a non-English language is active, yaak also instructs the LLM to write explanations, summaries, and cautions in that language (used with --explain mode). The structured output format is preserved for correct parsing.
Context mode
yaak always includes your current working directory in the system prompt. For richer context, pass --context to also include:
Project type detection — Cargo.toml, package.json, go.mod, Makefile, Dockerfile, and 15+ other markers.
Git branch — if you're in a git repository.
File listing — top-level non-hidden files (up to 30).
$ yaak build the project
# With --context: LLM knows it's a Rust project
$ yaak --context build the project
Command: cargo build --release
Context is opt-in to avoid leaking sensitive filenames to the LLM provider.
Cache mode
Every generated command is saved to ~/.config/yaak/cache.json, keyed by model and description. Use --cache to skip the API call when a matching entry exists.
yaak tries an exact match first. If none is found, it falls back to BM25 fuzzy matching — a term-frequency ranking algorithm that finds similar cached descriptions even when the wording differs. Stop words are stripped and terms are scored by relevance across all cached entries for the same model.
$ yaak list all docker containers
# Exact match — returns instantly
$ yaak --cache list all docker containers
(cached)
Command: docker ps -a
# Fuzzy match — similar wording also hits the cache
$ yaak --cache show docker containers
(cached) (similar: "list all docker containers")
Command: docker ps -a
Use --no-cache to force a fresh API call and skip saving the result.
Safety
yaak blocks destructive commands before execution. The following patterns are detected and rejected, including privilege-escalation variants (sudo, doas, pkexec — with flags, env wrappers, etc.) and piped/chained sequences:
> /dev/ • chmod 000 • :(){ :|:& };:
If a destructive command is detected, yaak prints a warning and asks for confirmation before executing.
Command: rm -rf ./*
blocked: Destructive command blocked: `rm` is not allowed.
Privilege escalation
Commands using sudo, doas, or pkexec that are not destructive trigger a separate confirmation prompt warning about elevated privileges. This applies even when flags or env wrappers are used (e.g. sudo -u root, sudo env VAR=val).
Command: sudo systemctl restart nginx
warning: ⚠ This command requires elevated privileges (sudo/doas/pkexec)
Run with elevated privileges? [y/N]
Compatible providers
yaak auto-detects the provider from the API base URL and uses the appropriate request format.
Anthropic (native Messages API)
Detected when the API base contains anthropic.com. Uses the Messages API with streaming.
Google Gemini (native Gemini API)
Detected when the API base contains generativelanguage.googleapis.com. Uses the Gemini streaming API with SSE.
OpenAI-compatible
All other providers use the /v1/chat/completions endpoint with streaming.
| Provider | API base | Key required |
|---|---|---|
| OpenAI | https://api.openai.com/v1 | Yes |
| Ollama | http://localhost:11434/v1 | No |
| Groq | https://api.groq.com/openai/v1 | Yes |
| Together AI | https://api.together.xyz/v1 | Yes |
| OpenRouter | https://openrouter.ai/api/v1 | Yes |
| Doubleword | https://api.doubleword.ai/v1 | Yes |
| LM Studio | http://localhost:1234/v1 | No |
| vLLM | http://localhost:8000/v1 | No |
| LocalAI | http://localhost:8080/v1 | No |
Troubleshooting
zsh: no matches found: it?
zsh treats ?, *, and other characters as glob wildcards. When you type yaak what time is it?, zsh tries to expand it? as a file pattern and fails.
Quick fix — quote your description:
Permanent fix — add a noglob alias to your ~/.zshrc:
$ source ~/.zshrc
The noglob prefix tells zsh to skip glob expansion for yaak, so ?, *, and other special characters just work without quoting.
bash: similar issues
bash does not expand ? if no matching files exist, so this is usually only a problem in zsh. If you do hit issues in bash, quote your description the same way.