QVeris CLI

The official command-line tool for the QVeris capability routing network. Discover, inspect, and call 10,000+ real-world, verified API capabilities directly from your terminal or agent framework.

Why CLI? Unlike MCP which injects tool schemas into every LLM prompt (consuming hundreds of tokens per tool), CLI runs as a subprocess — zero prompt tokens, deterministic output, instant startup.

Installation

One-liner (recommended)

curl -fsSL https://qveris.ai/cli/install | bash

The script checks Node.js 18+, installs @qverisai/cli globally, and adds it to your PATH.

npm

npm install -g @qverisai/cli

npx (no install)

npx @qverisai/cli discover "weather API"

Requirements

Node.js 18+
Zero runtime dependencies (uses only Node.js built-in APIs)

Quick Start

# Guided first call
qveris init

# Manual flow
# 1. Authenticate (saves key to ~/.config/qveris/config.json)
qveris login

# 2. Discover tools
qveris discover "weather forecast API"

# 3. Inspect a tool (use index from discover results)
qveris inspect 1

# 4. Call it
qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'

Commands

`qveris init`

Guided first-call wizard: resolve auth, discover a capability, inspect it, call it, and finish with usage/ledger reconciliation guidance.

qveris init [query] [flags]

Flag	Description	Default
`--query <query>`	Discovery query override	`weather forecast API`
`--params <json\|@file\|->`	Call parameters override	sample parameters when available
`--resume`	Reuse the last discovery session after a recoverable failure	false
`--dry-run`	Print planned discovery/call payload without executing the call	false
`--tool-id <id>`	Select a specific tool ID instead of the first result	first result
`--json`	Output machine-readable wizard state	false

Examples:

qveris init
qveris init --query "stock price API"
qveris init --dry-run
qveris init --resume --params '{"city": "London"}'

The final step prints exact qveris usage and qveris ledger commands so you can reconcile the call.

`qveris discover`

Search for API capabilities using natural language. Returns tool name, provider, ID, description, relevance score, success rate, latency, and billing rule metadata when available.

qveris discover <query> [flags]

Flag	Description	Default
`--limit <n>`	Max results to return	5
`--json`	Output raw JSON	false

Examples:

qveris discover "stock price API"
qveris discover "translate text to French" --limit 10
qveris discover "cryptocurrency market data" --json

Output fields per tool:

Tool name and provider
tool_id (used for inspect/call)
Description
Relevance score, success rate, latency, billing rule summary
Categories and region (if applicable)
Verified badge (if tool has execution history)

`qveris inspect`

View full details of a tool before calling it. Shows parameters with types, descriptions, enum values, provider info, and example parameters.

qveris inspect <tool_id|index> [flags]

Flag	Description
`--discovery-id <id>`	Reference a specific discovery session
`--json`	Output raw JSON

Numeric indexes (e.g., 1, 2) reference the last discover results.

Examples:

# By index from last discover
qveris inspect 1

# By tool ID
qveris inspect openweathermap.weather.current.v1

# Inspect multiple tools
qveris inspect 1 2 3

Output includes:

Tool name, ID, description
Provider name and description
Region, latency, success rate, billing rule
Parameters: name, type, required/optional, description, allowed values (enum)
Example parameters
Last execution record (if available)

`qveris call`

Execute a capability with parameters. Returns structured result data, execution time, pre-settlement billing, and remaining credits. Final charge status is available through qveris usage and qveris ledger.

qveris call <tool_id|index> [flags]

Flag	Description	Default
`--params <json\|@file\|->`	Parameters as JSON, file path, or stdin	`{}`
`--discovery-id <id>`	Discovery session ID	auto from session
`--max-size <bytes>`	Response size limit (-1 = unlimited)	4KB (TTY) / 20KB (pipe)
`--dry-run`	Preview request without executing	false
`--codegen <lang>`	Generate code snippet after call	—
`--json`	Output raw JSON	false

Parameter input methods:

# Inline JSON
qveris call 1 --params '{"city": "London"}'

# From file
qveris call 1 --params @params.json

# From stdin
echo '{"city": "London"}' | qveris call 1 --params -

Dry run (no credits consumed):

qveris call 1 --params '{"symbol": "AAPL"}' --dry-run

Code generation:

# Generate curl, Python, or JavaScript snippet after a successful call
qveris call 1 --params '{"symbol": "AAPL"}' --codegen curl
qveris call 1 --params '{"symbol": "AAPL"}' --codegen python
qveris call 1 --params '{"symbol": "AAPL"}' --codegen js

Response Truncation

For terminal use (TTY), results larger than 4KB are automatically truncated. The CLI shows:

A preview of the truncated content
An OSS download link (valid 120 minutes) for the full result
The response JSON schema so you understand the data structure
A hint: Use --max-size -1 for full output

For agent/script use (--json or piped output), the default increases to 20KB. Use --max-size -1 for unlimited.

`qveris mcp configure`

Generate MCP client configuration for Cursor, Claude Desktop, Claude Code, OpenCode, OpenClaw, or a generic stdio client. Print mode is the default and uses YOUR_QVERIS_API_KEY placeholders so the output is safe to paste into issues or docs. Placeholder output intentionally fails API key validation until you replace it or use --include-key.

qveris mcp configure --target cursor
qveris mcp configure --target cursor --write --include-key
qveris mcp configure --target claude-desktop --write --include-key
qveris mcp configure --target opencode --write --include-key
qveris mcp configure --target openclaw --write --include-key
qveris mcp configure --target claude-code
qveris mcp configure --target generic --json

Supported targets:

Target	Output
`cursor`	`~/.cursor/mcp.json`
`claude-desktop`	Claude Desktop MCP config
`claude-code`	`claude mcp add` command
`opencode`	OpenCode local MCP config
`openclaw`	OpenClaw qveris plugin config
`generic`	Raw stdio server JSON

Flags:

Flag	Description
`--target <target>`	Target client. Defaults to `cursor`
`--output <path>`	Override config output path
`--write`	Write the generated config to disk
`--include-key`	Include the resolved API key instead of the placeholder
`--json`	Output machine-readable JSON

`qveris mcp validate`

Validate an MCP config file. Static validation checks config shape, QVeris entry presence, API key wiring, and expected canonical tools.

qveris mcp validate --target cursor
qveris mcp validate --target cursor --output ~/.cursor/mcp.json

Add --probe to start the configured stdio server and confirm the discover, inspect, and call tools are visible via tools/list.

qveris mcp validate --target cursor --probe

--probe requires a runnable stdio command and a real QVERIS_API_KEY; it is not available for OpenClaw plugin configs.

`qveris login`

Authenticate with your QVeris API key. Opens the browser to the API key page and prompts for masked input.

qveris login [flags]

Flag	Description
`--token <key>`	Provide key directly (skip browser prompt)
`--no-browser`	Don't open browser

# Interactive (opens browser → masked input)
qveris login

# Non-interactive
qveris login --token "sk-1_your-key-here"

The key is saved to ~/.config/qveris/config.json with 0600 permissions (owner-only).

`qveris logout`

Remove stored API key from config.

qveris logout

`qveris whoami`

Show current auth status and key source, and validate against the API.

qveris whoami

`qveris credits`

Check remaining credit balance.

qveris credits

`qveris usage`

Query request-level usage audit without flooding Agent context. Defaults to summary mode and returns aggregates instead of full raw rows. Summary mode requests service-side summary=true aggregates when available and falls back to bounded client-side aggregation for older deployments.

qveris usage [flags]

Flag	Description
`--mode summary\|search\|export-file`	Output mode. Default: `summary`
`--start-date <YYYY-MM-DD>`	Range start
`--end-date <YYYY-MM-DD>`	Range end
`--bucket hour\|day\|week`	Aggregation bucket for summary
`--execution-id <id>`	Precise execution lookup
`--search-id <id>`	Precise search lookup
`--charge-outcome <value>`	`charged`, `included`, `failed_not_charged`, `failed_charged_review`
`--min-credits <n>`	Minimum credit amount
`--max-credits <n>`	Maximum credit amount
`--limit <n>`	Search row cap, default 10, hard max 50

Examples:

qveris usage --mode summary --bucket hour
qveris usage --mode search --execution-id <execution_id> --json
qveris usage --mode search --min-credits 30 --max-credits 100 --json
qveris usage --mode export-file --start-date 2026-05-01 --end-date 2026-05-04

`qveris ledger`

Query final credit ledger entries without dumping full account history. Defaults to summary mode. Summary mode requests service-side summary=true aggregates when available and falls back to bounded client-side aggregation for older deployments.

qveris ledger [flags]

Flag	Description
`--mode summary\|search\|export-file`	Output mode. Default: `summary`
`--start-date <YYYY-MM-DD>`	Range start
`--end-date <YYYY-MM-DD>`	Range end
`--bucket hour\|day\|week`	Aggregation bucket for summary
`--entry-type <type>`	Filter by ledger entry type
`--direction consume\|grant\|any`	Filter by debit/credit direction
`--min-credits <n>`	Minimum absolute credit amount
`--max-credits <n>`	Maximum absolute credit amount
`--limit <n>`	Search row cap, default 10, hard max 50

Examples:

qveris ledger --mode summary --bucket day
qveris ledger --mode search --direction consume --min-credits 50 --json
qveris ledger --mode export-file --start-date 2026-05-01 --end-date 2026-05-04

export-file writes JSONL under .qveris/exports/ and returns the path instead of printing every record.

`qveris interactive`

Launch a REPL session for chained discover/inspect/call workflows. Session state (discovery ID, results) is held in memory and persisted to disk.

qveris interactive [flags]

Aliases: qveris repl

REPL commands:

Command	Description
`discover <query>`	Find capabilities
`inspect <index\|id>`	View tool details
`call <index\|id> {json}`	Execute with inline params
`codegen <curl\|js\|python>`	Generate code from last call
`history`	Show session state
`help`	Show commands
`exit`	Quit

qveris> discover "crypto price API"
qveris> inspect 1
qveris> call 1 {"symbol": "BTC"}
qveris> codegen python
qveris> exit

`qveris doctor`

Self-check diagnostics: verifies Node.js version, API key configuration, base URL, and API connectivity.

qveris doctor

`qveris config`

Manage CLI settings.

qveris config <subcommand> [args]

Subcommand	Description
`set <key> <value>`	Set a config value
`get <key>`	Get a config value
`list`	List all settings with sources
`reset`	Reset to defaults
`path`	Print config file location

Config keys: api_key, base_url, default_limit, default_max_size, color, output_format

`qveris completions`

Generate shell completion scripts.

# Bash
eval "$(qveris completions bash)"

# Zsh
eval "$(qveris completions zsh)"

# Fish
qveris completions fish | source

`qveris history`

Show current session state (last discovery query, results, age).

qveris history [--clear]

Global Flags

Available on every command:

Flag	Short	Description
`--json`	`-j`	Output raw JSON (for agents/scripts)
`--api-key <key>`		Override API key for this command
`--base-url <url>`		Override API base URL
`--timeout <seconds>`		Request timeout
`--no-color`		Disable ANSI colors
`--verbose`	`-v`	Show detailed output
`--version`	`-V`	Print version
`--help`	`-h`	Show help

Supports --key=value syntax and combined short flags (-jv).

Use -- to end option parsing: qveris discover -- --literal-query.

Environment Variables

Variable	Description	Default
`QVERIS_API_KEY`	API authentication key	—
`QVERIS_BASE_URL`	Override API base URL	auto from key
`QVERIS_DEFAULT_LIMIT`	Default discover limit	5
`QVERIS_DEFAULT_MAX_SIZE`	Default response size limit	4096
`XDG_CONFIG_HOME`	Config directory base	`~/.config`
`NO_COLOR`	Disable colors (standard)	—
`FORCE_COLOR`	Force colors even in pipes	—

Priority: --flag > environment variable > config file > default

Session Management

After each discover, the CLI saves session state to ~/.config/qveris/.session.json:

Discovery ID
Query
Base URL
Result list (tool_id, name, provider)

Subsequent inspect and call commands auto-read this session, enabling numeric index shortcuts:

qveris discover "weather API"    # saves session
qveris inspect 1                  # uses index 1 from session
qveris call 2 --params '{...}'   # uses index 2 + discovery ID

Sessions expire after 30 minutes. Use qveris history to view and qveris history --clear to reset.

Agent / LLM Integration

Why CLI over MCP for agents?

	CLI	MCP
Token cost	Zero — runs as subprocess	High — tool schemas in every prompt turn
Scalability	10,000+ real-world, verified tools, no prompt bloat	Each tool adds ~200-500 tokens
Output	Deterministic, `--json` for parsing	Varies by client implementation
Debugging	Visible in terminal, `--dry-run`	Opaque, buried in MCP logs

Smart defaults

The CLI auto-detects agent vs human context:

Context	`max_response_size`	Behavior
Terminal (TTY)	4KB	Human-friendly, auto-truncate
Piped / scripted	20KB	Agent-friendly
`--json` flag	20KB	Explicit agent mode
`--max-size N`	N	User override

Scripting example

# Discover, extract tool ID, call, parse result
TOOL=$(qveris discover "weather" --json | jq -r '.results[0].tool_id')
SEARCH_ID=$(qveris discover "weather" --json | jq -r '.search_id')
qveris call "$TOOL" --discovery-id "$SEARCH_ID" --params '{"city":"London"}' --json | jq '.result.data'

Exit Codes

Following BSD sysexits.h conventions:

Code	Constant	Meaning
0	`EX_OK`	Success
2	`EX_USAGE`	Bad arguments
69	`EX_UNAVAILABLE`	Service unavailable
75	`EX_TEMPFAIL`	Timeout or rate limit
77	`EX_NOPERM`	Auth error or insufficient credits
78	`EX_CONFIG`	Missing API key

Legacy Aliases

For backward compatibility, the following aliases are supported with deprecation warnings:

Alias	Maps to
`search`	`discover`
`execute`	`call`
`invoke`	`call`
`get-by-ids`	`inspect`
`--search-id`	`--discovery-id`

Architecture

@qverisai/cli
├── bin/qveris.mjs           # Entry point
├── src/
│   ├── main.mjs              # Command dispatch + flag parsing
│   ├── commands/              # 12 command handlers
│   ├── client/api.mjs         # HTTP client (native fetch)
│   ├── client/auth.mjs        # API key resolution
│   ├── config/endpoint.mjs    # API endpoint resolution
│   ├── config/store.mjs       # Config file R/W (0600 perms)
│   ├── session/session.mjs    # Session persistence
│   ├── output/formatter.mjs   # Human-readable formatting
│   ├── output/codegen.mjs     # Code snippet generation
│   └── errors/handler.mjs     # Error handling + BSD exit codes
└── scripts/install.sh         # One-liner installer

Zero runtime dependencies. Node.js 18+ built-in APIs only. No chalk, no commander, no yargs.

QVeris CLI

Installation

One-liner (recommended)

npm

npx (no install)

Requirements

Quick Start

Commands

qveris init

qveris discover

qveris inspect

qveris call

Response Truncation

qveris mcp configure

qveris mcp validate

qveris login

qveris logout

qveris whoami

qveris credits

qveris usage

qveris ledger

qveris interactive

qveris doctor

qveris config

qveris completions

qveris history

Global Flags

Environment Variables

Session Management

Agent / LLM Integration

Why CLI over MCP for agents?

Smart defaults

Scripting example

Exit Codes

Legacy Aliases

Architecture

Links

`qveris init`

`qveris discover`

`qveris inspect`

`qveris call`

`qveris mcp configure`

`qveris mcp validate`

`qveris login`

`qveris logout`

`qveris whoami`

`qveris credits`

`qveris usage`

`qveris ledger`

`qveris interactive`

`qveris doctor`

`qveris config`

`qveris completions`

`qveris history`