# 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.

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

### Authentication methods

1. -
   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.
2. -
   OAuth login (planned): quelvio login will perform a browser-based device-code flow and stash the resulting token in your OS keychain.
3. -
   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'```

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

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

## Configuration

Environment variables and files that control CLI behavior.

## Exit codes

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

## 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.

## Links & references

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

## Related

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