Why ruask
| ⚡ Milliseconds for quick lookups | ruask tar or ruask git commit renders the local tldr page directly: no network, no model, no API key. |
| 📚 Answers grounded in docs | Questions like ruask git commit -q "how do I edit the last commit message" send the matching tldr pages to the model as reference, so it invents fewer flags. |
| 🔍 Explains command output | cat error.log | ruask cargo build -q "why did it fail" reads the output, the command and your question together. |
| 🖥️ Made for the terminal | Streams as it arrives, colors by meaning, numbers examples, never wraps a command. Redirected output stays plain text. |
| 🛡️ Safe by default | Shows commands, never runs them. Flags destructive ones (rm -r, git reset --hard, git push --force …). No history, no project .env loading. |
| 🔌 Bring your own model | OpenAI-compatible Chat Completions or native Anthropic Messages, configured once per user. |
Quick start
Runs on macOS and Linux (x86_64 / arm64). Install with whichever you prefer:
| Package manager | Command |
|---|---|
| Homebrew | brew install KevinGuo1007/tap/ruask |
| Install script | curl --proto '=https' --tlsv1.2 -LsSf https://github.com/KevinGuo1007/ruask/releases/latest/download/ruask-installer.sh | sh |
| Cargo | cargo install ruask --locked (builds from source; needs a Rust toolchain with 2024 edition support) or cargo binstall ruask |
| npm | npm install -g ruask |
Prebuilt binaries are also on GitHub Releases, each archive with a .sha256 checksum. The install script puts ruask in $XDG_BIN_HOME or ~/.local/bin.
# fill in your model's base_url, api_key and model, then:
Make sure Cargo's bin directory (usually ~/.cargo/bin) is on your PATH.
How it works
flowchart LR
Q["ruask args / stdin"] --> R{"command only?<br/>no -q, no stdin"}
R -- "yes, page installed" --> T["render local tldr page<br/><i>milliseconds, offline</i>"]
R -- "no" --> P["attach matching tldr pages<br/>as reference"]
P --> M["stream from your model"]
M --> O["render line by line<br/>colors · numbering · warnings"]
Pages are installed by ruask --update-pages into $RUASK_TLDR_DIR, or $XDG_DATA_HOME/ruask/tldr, or ~/.local/share/ruask/tldr. Only English and Simplified Chinese pages are kept. Without pages, every query goes to the model as before.
Usage
| Command | What happens |
|---|---|
ruask cargo |
Look up a command |
ruask git commit |
Look up a subcommand (positional args are joined) |
ruask "find the process listening on port 8080" |
Natural-language task |
ruask git commit -q "how do I undo a commit" |
Command plus a focused question |
ruask --question "how do I watch a log file" |
A question on its own |
cat error.log | ruask cargo build -q "why did it fail" |
Explain piped output (up to 64 KiB) |
ruask tar -xzvf |
Unknown options after the command word belong to the target command |
ruask -- git log -p |
Use -- (or quotes) when a target option clashes with ruask's own |
ruask -L zh -p linux "check disk usage" |
Pick answer language (en / zh) and target platform (linux / macos) |
ruask git status > usage.txt |
stdout carries only the answer, as plain text |
ruask --version |
Version and local tldr page status |
Run ruask -h for short help or ruask --help for the full one.
Configuration
ruask --init-config creates $XDG_CONFIG_HOME/ruask/config.toml (default ~/.config/ruask/config.toml) with 0600 permissions and keeps an existing file.
= "openai" # or "anthropic"
# language = "en" # en / zh; defaults to your locale, then English
[]
= "https://your-provider.example/v1" # /chat/completions is appended
= "your-model"
= "YOUR_API_KEY"
# thinking = "disabled" # only for services that support thinking.type; usually much faster
[]
= "https://your-anthropic-provider.example/v1" # /messages is appended
= "your-model"
= "YOUR_API_KEY"
Environment variables override the file field by field for the selected protocol and never borrow from the other one:
| Protocol | Variables |
|---|---|
| selection | RUASK_API_TYPE (openai / anthropic) |
openai |
OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL, OPENAI_THINKING |
anthropic |
ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_MODEL, ANTHROPIC_WORKSPACE_ID |
ruask never reads .env files from your project and never edits shell startup files. Full details, including streaming fallback rules and the Anthropic headers, are in the reference.
Output and exit codes
- stdout carries only the answer; stderr carries notices, the waiting spinner and the source line (model · elapsed time · tldr pages used).
- Color follows
--color auto|always|neverandNO_COLOR. Placeholders such as{{file}}show as underlined italics in a terminal and stay literal when redirected. - A stream that breaks after output has started keeps what was shown and exits with
5. Nothing is retried or replayed.
| Code | Meaning |
|---|---|
0 |
success |
1 |
other error |
2 |
usage or input error |
3 |
configuration error |
4 |
connection or service error |
5 |
incomplete answer |
Documentation
- Behavior reference: protocols, streaming, configuration, input and output rules (Chinese)
- Development guide · Testing · Performance notes
- Website, with a 20-second launch video
Development
Tests need no real API key. They start local HTTP stand-ins on random ports and, on macOS/Linux, a pseudo-terminal for color tests. The website lives in site/ (Vite + React) and deploys to Vercel from main.
Not yet on crates.io, Homebrew or as prebuilt binaries. Windows is out of scope for now.
License
ruask is released under the MIT License.
Local page content comes from tldr-pages under CC BY 4.0 and is not bundled with ruask.