ruask 0.1.0

A command-line assistant for command lookup and command output explanation
ruask-0.1.0 is not a library.

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.

ruask --update-pages      # optional, recommended: download and verify the official tldr pages
ruask tar                 # local page, no configuration needed

ruask --init-config       # create a 0600 config template and print its path
# fill in your model's base_url, api_key and model, then:
ruask "find files larger than 100 MB"
git clone https://github.com/KevinGuo1007/ruask
cd ruask
cargo install --path .    # or: cargo build --release && ./target/release/ruask

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.

api_type = "openai"          # or "anthropic"
# language = "en"            # en / zh; defaults to your locale, then English

[openai]
base_url = "https://your-provider.example/v1"   # /chat/completions is appended
model = "your-model"
api_key = "YOUR_API_KEY"
# thinking = "disabled"      # only for services that support thinking.type; usually much faster

[anthropic]
base_url = "https://your-anthropic-provider.example/v1"   # /messages is appended
model = "your-model"
api_key = "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|never and NO_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

Development

cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings

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.