--- title: Quelvio CLI: company knowledge in your terminal slug: quelvio-cli-launch category: Company tags: CLI, MCP, Agents date: 2026-05-22 read_time: 6 min read word_count: 1290 canonical: https://quelvio.com/blog/quelvio-cli-launch machine_url: https://quelvio.com/ai/blog/quelvio-cli-launch publisher: Quelvio ---
# Quelvio CLI: company knowledge in your terminal
Company · May 22, 2026 · 6 min read
Completions, smart hints, progress indicators, update-check, and $EDITOR multiline. Why a CLI when Quelvio already speaks MCP — and what authority-scored, lifecycle-aware retrieval looks like at a shell prompt.
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](https://github.com/Quelvio/quelvio-agent-skills). 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.
```shquelvio 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 + tenant```Two 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.
```sh# 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.fish```**Smart 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.
[Concrete shape] Ask a naive RAG-over-an-index system *"what's our rollback procedure for the payments service?"* and it hands you the highest-cosine-similarity match — which may well be a 2024 wiki page nobody has updated since the cutover. Ask the same of `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:
```shnpm install -g @quelvio/cli```Node 20.10 or newer. Then:
```shquelvio 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](/docs/cli).
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](/docs/mcp) 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](https://github.com/Quelvio/quelvio-agent-skills) 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.
Tags: CLI, MCP, Agents