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.

@qverisai/cli v0.9.0 is the latest tested release. It includes OAuth Device Flow sessions, zero-cost parameter/quote probes, and opt-in discovery and call projections while preserving API key compatibility.

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
`--view <routing\|full>`	Compact routing cards or complete results	full
`--lang <zh\|en>`	Response language	server negotiation
`--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
qveris discover "weather forecast" --view routing --lang en

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

Validate candidate parameters and obtain a zero-cost quote without executing the capability.

qveris probe <tool_id|index> --params '{"city":"London"}' --checks schema,quote

--checks accepts schema, quote, coverage, and sample; --live-budget accepts none, metadata, and sampled. The current contract implements schema and quote. Coverage and sample may return unknown. Probe does not execute the capability or consume credits.

`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)
`--respond-with <mode>`	`full`, `summary`, or `fields:<JSONPath,...>`	full
`--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 -
 
# Compact schema/size summary with a signed full-content URL
qveris call 1 --params '{"city": "London"}' --respond-with summary
 
# Select fields rooted at result.data
qveris call 1 --params '{"city": "London"}' --respond-with 'fields:$.temperature,$.humidity'

Projection flags are opt-in. If an older service explicitly rejects a projection field as unknown, the CLI retries once without only that field. Invalid projections remain 422 errors.

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, probe, 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 auth login/status/logout`#

Use OAuth Device Flow on a local or headless terminal without copying an API key. The CLI discovers all OAuth endpoints from the selected API origin, opens the verification page, and polls at the server-provided interval.

qveris auth login
qveris auth status
qveris auth logout

Refresh credentials are rotated automatically and stored in the operating-system credential store. If no credential store is available, the CLI limits the credential to the current process by default. On a trusted headless host, add --allow-unencrypted-storage to explicitly persist the tokens in the user-only config file (0600 permissions). auth logout attempts remote revocation before clearing local credentials. An explicitly configured API key keeps its existing priority and behavior.

The persisted OAuth session also remembers its API endpoint for later CLI processes. An explicit --base-url or QVERIS_BASE_URL still takes precedence and must match the session issuer.

Use --no-browser --allow-unencrypted-storage on a trusted headless host that has no operating-system credential store. Advanced integrations can narrow the request with --scope <scopes> and --resource <url>; both must match the server's published contract, and a custom scope must retain offline_access so the session can refresh safely.

`qveris login` (API key)#

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 for a working first call. Checks Node.js version, the active API key or OAuth session, the API endpoint, then a free discover probe covering connectivity, credential validity, remaining credits, and response-shape conformance to the CLI contract. Each failure prints an actionable fix. Diagnostics consume no credits (discover is free). Add --json for machine-readable output.

qveris doctor
qveris doctor --json

`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, 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	Built-in default
`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

For the API endpoint specifically, resolution is --base-url > QVERIS_BASE_URL > stored OAuth session endpoint (when OAuth is active) > built-in default. API keys never select or replace the endpoint. Override values must be complete HTTP(S) URLs without credentials, query parameters, or fragments.

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

qveris call#

Response Truncation#

qveris mcp configure#

qveris mcp validate#

qveris auth login/status/logout#

qveris login (API key)#

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

`qveris call`#

`qveris mcp configure`#

`qveris mcp validate`#

`qveris auth login/status/logout`#

`qveris login` (API key)#

`qveris logout`#

`qveris whoami`#

`qveris credits`#

`qveris usage`#

`qveris ledger`#

`qveris interactive`#

`qveris doctor`#

`qveris config`#

`qveris completions`#

`qveris history`#