The Quelvio CLI is a single npm binary — @quelvio/cli — that takes a natural-language question, hits Quelvio Brain, and returns a cited answer in your terminal. It is the same retrieval pipeline that powers our MCP server, our REST API, our Slack and Teams bots, and the dashboard — exposed in the shape a terminal-resident agent or a human at a prompt actually wants.
A reasonable question is: why a CLI when we already ship MCP? Because agents come in different shapes. Claude Desktop, Cursor, and ChatGPT custom connectors speak MCP, and Quelvio meets them there. But Claude Code, OpenAI's Codex CLI, GitHub Actions runners, and the engineer typing into a tmux pane all live in the terminal. MCP is the wrong shape for them. Same brain, different surface.
The shape of the integration problem
MCP solved one specific problem well — it gave agents a uniform way to discover and call tools across servers, with the runtime handling auth, transport, and capability negotiation. If you run inside a host that already speaks MCP, plugging Quelvio in is a configuration change. We have docs for that.
But MCP assumes a host. A Claude Code session, or an Anthropic SDK script running inside bash, is the host; there is no MCP runtime layered above it. Forcing one in is heavy — another process to manage, another connection lifecycle, another set of credentials in another place. The right shape for that environment is the shape every other piece of dev tooling already takes: a binary on PATH that reads stdin, writes stdout, and obeys exit codes.
That is what quelvio is. One binary, every connector behind it. Pipe to jq. Exit on non-zero. Drop it into a Makefile. The CLI doesn't compete with the MCP server; it covers the half of the integration surface MCP doesn't reach.
The companion piece is the agent-skills repo. Per-runtime skill files — Claude Code, Cursor, Codex CLI, MCP — that teach the host agent when to reach for quelvio query. The skill turns the CLI into native vocabulary: the agent sees a question about internal company knowledge and knows there is a command that can answer it, not just "the web."
What the CLI actually does
The surface area is small on purpose. Five primary commands and the polish that makes them feel native.
quelvio login # device-flow OAuth, token in OS keychain
quelvio query "what is our SLA?" # synthesized, cited answer
quelvio domains # taxonomy domains + coverage levels
quelvio source <query-id> # per-chunk provenance, zero cost
quelvio whoami # signed-in identity + tenantTwo flags carry most of the weight. --mode deep widens retrieval and runs premium synthesis when the question is worth it; --json swaps the prose output for a machine-readable response that any downstream agent can parse.
Underneath the commands sits the polish that makes the CLI stop feeling like a wrapper and start feeling like a tool. Five things make that real.
Shell completions across bash, zsh, and fish. Run quelvio completion zsh and pipe the output where your shell expects it. Tab-complete commands, flags, and the values for --mode. The most common path to "this works the way I expect" in a CLI is making it answer to muscle memory.
# zsh: drop completions into a fpath directory
quelvio completion zsh > "${fpath[1]}/_quelvio"
# bash: append to ~/.bashrc once
echo 'source <(quelvio completion bash)' >> ~/.bashrc
# fish: standard completions dir
quelvio completion fish > ~/.config/fish/completions/quelvio.fishSmart error hints. Every stratified exit code now carries a one-line suggestion in stderr. Exit 2 ("no token") tells you to export QUELVIO_TOKEN or run quelvio login. Exit 4 ("rate limited") quotes the Retry-After and reminds you the daily kT pool resets at 00:00 UTC. The CLI knows what to try next; it should say so.
Progress indicators on --mode deep. Deep mode takes a few seconds — wider retrieval, premium synthesis. The CLI now streams the pipeline transitions so you see where time is going: connecting → retrieving → re-ranking → synthesizing. Spinners auto-disable when stdout isn't a TTY, so piped scripts stay clean.
Daily update-check probe. The CLI quietly checks npm for new releases, at most once a day, and prints a one-line notice when a newer version is available. Set QUELVIO_UPDATE_CHECK=0 to turn it off — we honor that variable everywhere it could surprise you.
$EDITOR multiline query. Run quelvio query with no positional argument and no piped stdin; the CLI opens $EDITOR (or vi) on a scratch file, strips lines starting with #, and sends the rest. Drafting a real question in vim beats wrestling it into a single quoted string every time.
Authority, lifecycle, supersession — in the terminal
What ships in the terminal is what ships everywhere — the same brain, with the same posture.
Quelvio ranks sources by authority, scored per contributor per domain. The CTO's note on the auth rewrite outweighs a junior engineer's hot take in a side channel; the engineer who actually wrote the payment system outweighs the CTO when the question is about payment edge cases. Authority is conditional.
Results are lifecycle-aware. Drafts, current canonical documents, superseded memos, and deprecated runbooks all get labeled distinctly. Stale content is demoted. Where one document supersedes another, the answer says so.
When the corpus does not contain enough signal, the CLI refuses. Confidently-wrong is the failure mode of every system that grounds answers in retrieved fragments; we treat it as a bug.
Every claim cites the chunk it came from. Run quelvio source <query-id> to see the document path, connector, lifecycle state, contributor, and last-update time for each citation. That call consumes zero Knowledge Tokens.
quelvio query and you get either the post-cutover procedure with the older one labeled as superseded, or — if the corpus genuinely doesn't carry a current answer — a refusal with the gap surfaced. Either is a better answer than the confident-wrong one.Install and try
One command:
npm install -g @quelvio/cliNode 20.10 or newer. Then:
quelvio login
quelvio query "what does our team know about kT pricing?"quelvio login runs the OAuth device-code flow against the dashboard at enterprise.quelvio.com/device. The resulting token lands in your OS keychain — Keychain on macOS, the appropriate native store on Windows and Linux. If you'd rather use a Personal Access Token in CI, set QUELVIO_TOKEN; the flag → env → keychain → config precedence is documented in full on the CLI reference page.
Roadmap: single-file native binaries and a Homebrew formula are next. For now, install via npm. If you're outside the terminal — Claude Desktop, Cursor, Claude.ai, ChatGPT — the MCP server is the right entry point. Same brain, OAuth-protected, no Node required.
What's next
The CLI is one move in a longer integration plan. The agent-skills repo gives each runtime — Claude Code, Cursor, Codex, MCP — a per-agent skill file that turns quelvio query into native vocabulary. The MCP server is live today and covers everything that isn't terminal-resident. Native binaries and a Homebrew formula come next, followed by first-class adapters for LangChain, LlamaIndex, and the Vercel AI SDK.
The thesis underneath all of it is the same: agents come in many shapes. The knowledge brain has to meet each one in the shape it already takes.