quelvio.com
human view ↗
---
title: CLI · Quelvio docs
canonical: https://quelvio.com/docs/cli
machine_url: https://quelvio.com/ai/docs/cli
install: npm i -g @quelvio/cli
---

# Your company's brain, scripted from the terminal.

Docs · CLI

`quelvio` is the official command-line client for the Quelvio Enterprise API. It puts every connected source — Drive, SharePoint, Confluence, Slack, Notion — behind a single, scriptable interface that returns cited, synthesized answers in human-readable or JSON form. Every request is attributed to the human running it via their Personal Access Token, so audits stay clean and per-employee permission filters apply automatically.

[Install](#install) · [View on GitHub](https://github.com/Quelvio/quelvio-cli)

[Prefer a GUI?] If you live in Claude Desktop, Cursor, or another Model Context Protocol client, install the Quelvio MCP server instead — same retrieval pipeline, same per-employee identity, no terminal required. [MCP server docs](/docs/mcp)

## Install

Install via npm. Node 20.10 or newer is required.

### npm (recommended)

Global install gives you the `quelvio` binary on your PATH.

```shnpm i -g @quelvio/cli
quelvio --version```

### From source

Useful when you want to track main or contribute. Requires pnpm.

```shgit clone https://github.com/Quelvio/quelvio-cli
cd quelvio-cli
pnpm install
pnpm build
node dist/index.js --version```

### Native binaries · Homebrew

Single-file binaries for macOS, Linux, Windows, and Homebrew are planned. Until then, install via npm.

## Quickstart

Three commands and you're querying production knowledge.

  1. 1.Generate a Personal Access Token — Sign in to the dashboard at enterprise.quelvio.com/account, open Personal API Keys, and click Create token. Tokens are scoped to your individual identity — every query you run is attributed to you and respects your per-source permissions. [enterprise.quelvio.com/account](https://enterprise.quelvio.com/account)
  2. 2.Export it
    ```shexport QUELVIO_TOKEN=qlv_pat_<your-key>```
  3. 3.Verify auth, then ask the brain a question
    ```shquelvio whoami
quelvio query "what is our deployment process?"```

## Authentication

`quelvio` resolves a token from the following sources, in order, and uses the first non-empty one. The token is never echoed to stdout, stderr, or logs — `--verbose` HTTP traces redact the `Authorization` header.

  1. 1.--token <t> flag — Overrides everything; never persisted.
  2. 2.QUELVIO_TOKEN env var — Recommended for CI and ad-hoc shells.
  3. 3.OS keychain — Populated by quelvio login when browser-based login is available.
  4. 4.~/.quelvio/config.json — Fallback when the OS keychain is unavailable (e.g. headless Linux).

### Authentication methods

  • -PAT (available now) — A long-lived bearer token tied to a human user. Every query is attributed to that user; permissions and rate limits apply per identity. Generate one at enterprise.quelvio.com/account.
  • -OAuth login (planned) — quelvio login will perform a browser-based device-code flow and stash the resulting token in your OS keychain.
  • -Service accounts (planned) — For headless agents and CI bots that need an identity distinct from a human's.

## Commands

Every command supports the global flags `--token <t>`, `--json`, `--no-color`, `--verbose`, and `--quiet`. Run `quelvio <command> --help` for the full flag list.

### quelvio query <text>

Ask the brain a natural-language question.

```shquelvio query "what is our incident response policy?"
quelvio query --mode deep --max-sources 8 "compare our Q3 vs Q4 deployment cadence"
quelvio query --domain engineering.platform "who owns the auth middleware?"
echo "draft a release note for v1.4" | quelvio query
quelvio query --json "what is our SLA?" | jq '.synthesis'```
  • ---mode <m> (default standard) — fast (retrieval only, no synthesis), standard (default), or deep (wider retrieval + premium synthesis).
  • ---max-sources <n> (default 5) — Number of source chunks (1–10).
  • ---domain <d> (default —) — Restrict to a taxonomy domain (e.g. engineering.platform). Discover values with quelvio domains.
  • ---stream (default off) — Stream synthesis tokens as they arrive (SSE). Falls back to non-streaming if unsupported.
  • ---no-wait (default off) — Return the query_id immediately for async polling.
  • ---json (default off) — Emit the raw API response as JSON.
  • ---quiet (default off) — Suppress the metadata footer (Query ID, kT, latency).

If no positional text is given, piped stdin is read and used as the query; otherwise $EDITOR (or vi) opens for a multi-line prompt.

<synthesized answer with [1] [2] citation markers>

Sources:
  [1] runbooks/incident-response.md (confluence) — [email protected], 3d ago
  [2] eng-week-2026-04-15.slack (slack) — [email protected], 2w ago

Query ID: 9f3a-...  ·  Coverage: high  ·  kT: 12500  ·  1820ms

### quelvio domains

List the tenant's taxonomy domains, with coverage levels — useful before issuing a billable query.

```shquelvio domains
quelvio domains --json | jq '.domains[].taxonomy_domain'```

### quelvio source <query-id>

Show per-chunk provenance for a previous query — document path, connector, lifecycle state, embedded timestamp, contributor, last source update.

```shquelvio source 9f3a4d8c-7b2e-4a3d-b1c5-1f2e3d4a5b6c
quelvio source 9f3a... --json```

This call consumes zero Knowledge Tokens.

### quelvio whoami

Print the signed-in identity, tenant, auth method, and a redacted token prefix.

```shquelvio whoami
quelvio whoami --json```
Signed in as: [email protected]
Tenant:       ACME Corp (aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee)
Auth method:  pat
Token prefix: qlv_pat_a1b2...

### quelvio config <list|get|set|unset>

Persist defaults in ~/.quelvio/config.json so you don't repeat flags.

```shquelvio config list
quelvio config get default_mode
quelvio config set default_mode deep
quelvio config set default_max_sources 8
quelvio config set api_base https://api.staging.quelvio.com
quelvio config unset api_base```
  • -api_base (URL, default https://api.quelvio.com)
  • -default_mode (enum, default standard)
  • -default_max_sources (int 1–10, default 5)

config list never prints the token — use the keychain or QUELVIO_TOKEN env var instead.

## Configuration

Environment variables and files that control CLI behavior.

  • -QUELVIO_TOKEN — Personal Access Token. Highest-precedence non-flag source.
  • -QUELVIO_API_BASE — Override the API base URL (defaults to https://api.quelvio.com). Useful for staging.
  • -NO_COLOR — Set to any non-empty value to suppress ANSI colors. Standard across CLIs; quelvio honors it.
  • -EDITOR / VISUAL — Used by quelvio query when no positional text and stdin is a TTY.
  • -~/.quelvio/config.json — Persisted defaults (mode 0600). Also holds the token when the OS keychain isn't available.

## Exit codes

Stable exit codes so scripts can branch on outcome without parsing stderr.

  • -0 — success
  • -1 — generic / unknown error
  • -2 — authentication problem — missing token, expired token, 401 from backend
  • -3 — resource not found (404)
  • -4 — rate limited (429) — see the Retry-After hint in stderr
  • -5 — response truncated (synthesis exceeded the 25k-token cap)
  • -6 — scope / permission error (403)
  • -7 — network error — DNS failure, connection refused, TLS error

## Output formats

Humans. The default output is prose with ANSI color, citation bolding, and a metadata footer. Colors auto-disable when stdout is not a TTY or when NO_COLOR is set.

Agents and scripts. Add --json to any command for a machine-readable response. Pretty-printed when stdout is a TTY, compact when piped — always parseable by jq.

```shquelvio query "what is our SLA?" --json | jq -r '.synthesis'
quelvio domains --json | jq -r '.domains[] | "\(.taxonomy_domain)\t\(.document_count)"'```

## Examples

Patterns we use ourselves.

### Bash one-liner

Pipe synthesized answers through jq into a Markdown file.

```shQUELVIO_TOKEN="qlv_pat_..." \
  quelvio query --json "summarize our security policies" \
  | jq -r '.synthesis' \
  | tee summary.md```

### GitHub Actions

Store your PAT as a repository secret (QUELVIO_PAT) and generate a knowledge digest on a schedule.

```yamlname: nightly-knowledge-digest
on:
  schedule:
    - cron: '0 13 * * *'
jobs:
  digest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm i -g @quelvio/cli
      - name: Generate digest
        env:
          QUELVIO_TOKEN: ${{ secrets.QUELVIO_PAT }}
        run: |
          quelvio query "what changed in eng this week?" --mode deep --json \
            | jq -r '.synthesis' > digest.md
      - uses: actions/upload-artifact@v4
        with:
          name: digest
          path: digest.md```

### AI coding agents

AI coding agents like Claude Code, Cursor, and OpenAI Codex can invoke the Quelvio CLI natively. Drop the matching SKILL.md from the agent-skills repo into your agent's runtime and it will reach for `quelvio query` whenever a question lands on internal company knowledge.

```shquelvio query "what is the rollback procedure for production deploys?"```

[Agent skills] Per-agent skill files for Claude Code, Cursor, Codex, and any MCP-compatible runtime live at github.com/Quelvio/quelvio-agent-skills. [repo](https://github.com/Quelvio/quelvio-agent-skills)

## Troubleshooting

Most failures fall into a handful of buckets. `--verbose` adds HTTP trace lines to stderr — useful when reporting issues.

  • -No authentication token found. (exit 2) — Export QUELVIO_TOKEN, or pass --token <t>.
  • -Authentication failed: Invalid enterprise API key. (exit 2) — Token revoked, expired, or copied incorrectly. Generate a new one at enterprise.quelvio.com/account.
  • -Forbidden: ... (exit 6) — The token's identity lacks permission for that document/domain. Ask the tenant owner; permission filters apply per user.
  • -Rate limited: ... (retry after Ns) (exit 4) — Back off N seconds; the CLI doesn't auto-retry 429. Your daily kT pool resets at 00:00 UTC.
  • -Network error: ... (exit 7) — DNS or TLS failure. Check connectivity to api.quelvio.com; try curl -v https://api.quelvio.com/openapi.json.
  • -OS keychain unavailable; using ~/.quelvio/config.json — Linux without libsecret. Install libsecret-1-0 (Debian/Ubuntu) or libsecret (Fedora/Arch) to use the OS keychain.
  • -default_max_sources must be an integer 1-10 — The backend caps results at 10 chunks. Lower the value.

## Links & references

## Related