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

Docs · CLI · Human page: https://quelvio.com/docs/cli · Machine view: https://quelvio.com/ai/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](https://quelvio.com/docs/cli#install) · [View on GitHub](https://github.com/Quelvio/quelvio-cli)

Install: `npm i -g @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](https://quelvio.com/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.

```sh
npm i -g @quelvio/cli
quelvio --version
```

### From source

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

```sh
git 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. **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. **Export it**

   ```sh
   export QUELVIO_TOKEN=qlv_pat_<your-key>
   ```
3. **Verify auth, then ask the brain a question**

   ```sh
   quelvio 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.

| Precedence | Source | Notes |
| --- | --- | --- |
| 1 | --token \<t> flag | Overrides everything; never persisted. |
| 2 | QUELVIO_TOKEN env var | Recommended for CI and ad-hoc shells. |
| 3 | OS keychain | Populated by quelvio login when browser-based login is available. |
| 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.

```sh
quelvio 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'
```

| Flag | Default | Notes |
| --- | --- | --- |
| `--mode <m>` | standard | fast (retrieval only, no synthesis), standard (default), or deep (wider retrieval + premium synthesis). |
| `--max-sources <n>` | 5 | Number of source chunks (1–10). |
| `--domain <d>` | — | Restrict to a taxonomy domain (e.g. engineering.platform). Discover values with quelvio domains. |
| `--stream` | off | Stream synthesis tokens as they arrive (SSE). Falls back to non-streaming if unsupported. |
| `--no-wait` | off | Return the query_id immediately for async polling. |
| `--json` | off | Emit the raw API response as JSON. |
| `--quiet` | 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) — alice@acme.com, 3d ago
  [2] eng-week-2026-04-15.slack (slack) — bob@acme.com, 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.

```sh
quelvio 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.

```sh
quelvio 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.

```sh
quelvio whoami
quelvio whoami --json
```

```
Signed in as: alice@acme.com
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.

```sh
quelvio 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
```

| Key | Type | Default |
| --- | --- | --- |
| `api_base` | URL | https://api.quelvio.com |
| `default_mode` | enum | standard |
| `default_max_sources` | int 1–10 | 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.

| Name | Purpose |
| --- | --- |
| `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.

| Code | Meaning |
| --- | --- |
| 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.

```sh
quelvio 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.

```sh
QUELVIO_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.

```yaml
name: 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.

```sh
quelvio 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.

| Symptom | Fix |
| --- | --- |
| 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

- [Quelvio for AI agents](https://quelvio.com/docs/ai-agents) (Use case): Per-agent quickstarts: Claude Code, Cursor, Codex, MCP
- [Quelvio/quelvio-cli](https://github.com/Quelvio/quelvio-cli) (GitHub): Source, README, CHANGELOG, issues
- [enterprise.quelvio.com/account](https://enterprise.quelvio.com/account) (Dashboard): Generate Personal Access Tokens
- [Quelvio/quelvio-agent-skills](https://github.com/Quelvio/quelvio-agent-skills) (Agent skills): Skill files for Claude Code, Cursor, Codex, and MCP agents
- [Quelvio MCP server](https://quelvio.com/docs/mcp) (Also see): Same brain, exposed over Model Context Protocol

## Related

- [Human view of this page](https://quelvio.com/docs/cli)
- [MCP server docs](https://quelvio.com/docs/mcp.md)
- [Everything for agents: llms.txt](https://quelvio.com/llms.txt)