huh: an LLM in your terminal

I built huh to answer quick technical questions without breaking my terminal flow. Instead of opening a browser tab, switching into a chat app, and pasting the result back into the shell, I can ask the question where the work is happening and get an answer that streams into the terminal.

It turns out that most of my questions are small: how do I write a command I keep forgetting, why did a build fail, what this file does, or which of two tools fits this job. huh is optimized for those questions.

What it does

• Streams answers from OpenRouter as they arrive.
• Renders Markdown when stdout is a terminal: headings, lists, links, inline code, fenced code blocks, and aligned tables.
• Leaves output as raw Markdown when piped, so it composes with the rest of the shell.
• Uses OpenRouter’s web search tool automatically when a question needs current information, with -s to force a search and -ns to disable it.
• Attaches files explicitly with -f path, or opens an interactive picker with -f that filters paths while you type.
• Continues a conversation with -c, trimming history to a sane character and message budget.
• Stores the API key, model, and search mode in XDG config paths with private permissions.
• Supports piped prompts, -- for prompts that start with -, NO_COLOR, and per-request model overrides.

Install

curl -LsSf https://olisemeka.dev/huh/install.sh | sh

The installer downloads the latest GitHub release, verifies its SHA-256 checksum, and installs to ~/.local/bin/huh. It supports Linux x86_64 and aarch64 (static musl builds) and macOS on Intel and Apple silicon.

Windows (PowerShell):

irm https://olisemeka.dev/huh/install.ps1 | iex

The PowerShell installer installs to %USERPROFILE%\.local\bin and adds it to your user PATH.

Set HUH_INSTALL_DIR to install somewhere else, or pin a release with HUH_VERSION=v0.1.0.

Save an API key once:

huh --login

Or export it:

export OPENROUTER_API_KEY="sk-..."

Examples

The example I use most often is asking for a command whose exact syntax I have forgotten:

huh how do I create a new Git repo and push it to GitHub

That produces the short sequence I need, including the difference between the GitHub CLI path and the plain Git path:

git init
git add .
git commit -m "Initial commit"
gh repo create my-project --public --source=. --remote=origin --push

Quotes are optional for ordinary words: huh why is the sky blue works because the remaining arguments are joined into one question. Quote the prompt when it contains shell characters such as ?, *, |, $, or (, and use -- when it starts with -.

Some other things I ask it:

huh git: undo the last commit but keep the changes
huh how do I rebase onto main and resolve conflicts
huh what is the rsync command to copy a folder but skip node_modules
huh compare Postgres and SQLite for a small local app

It is also useful for reading code I did not write:

huh -f src/main.rs
huh -f build.log why did this build fail
huh -f Cargo.toml -f src/main.rs review these files for problems

huh -f src/main.rs opens the question prompt with Explain this file. as the default, so pressing Enter is enough. huh -f without a path opens the autocomplete picker instead.

For questions that need current information:

huh -s what changed in the latest Rust release

Follow-ups work the same way:

huh explain Rust ownership
huh -c now show a small example

And when a question deserves a stronger model:

huh -m openai/gpt-5-mini review this architecture and list the risks

How it works

huh is a Rust CLI built around a streaming OpenAI-compatible chat completions request. The request is a POST to OpenRouter with stream: true; the response is a server-sent event stream. Each event is parsed incrementally, and content is passed through a small Markdown renderer that can handle partial chunks, fenced code, tables, and inline styling without waiting for the full answer.

The current version deliberately stays small:

• The release binary is about 3.2 MB and starts in roughly 2 ms on this machine.
• The dependency tree is around 60 crates.
• A clean release build takes about 30 seconds; an incremental rebuild takes about 3 seconds.
• The HTTP layer is synchronous ureq with rustls. Replacing the original reqwest/tokio stack removed the async runtime, hyper, tower, and the ICU4X data pulled in through URL parsing.
• Retries, timeouts, 429/5xx handling, and Retry-After behavior are covered by a local mock HTTP server in the test suite.
• The interactive picker is built on inquire and crossterm, so it works on Linux, macOS, and Windows.
• Config and session files are written atomically with private permissions.

The test suite covers the stream parser, Markdown rendering, file limits, prompt composition, session trimming, CLI parsing, picker filtering, HTTP retries, and error paths.

Links

• Source: github.com/OliseNS/huh
• Installer: olisemeka.dev/huh/install.sh
• OpenRouter: openrouter.ai