QVeris CLI

Discover, inspect, and call 10,000+ API capabilities from your terminal.

New users can run the guided first-call wizard:

qveris init

$ qveris discover "weather forecast API"
Found 5 capabilities matching your query

1. icons
   weather_gov.icons.retrieve.v3.ad0b4d80
   Returns a forecast icon. Icon services in API are deprecated.
   relevance: 99%  ·  success: 100.0%  ·  latency: ~325ms  ·  billing: Charged 5.75 credits per call

2. Weather Information Retrieve
   amap_webservice.weather.weatherinfo.retrieve.v3
   Query current (base) or future (all) weather information for a specified city using adcode.
   relevance: 96%  ·  success: 83.0%  ·  latency: ~467ms  ·  billing: Charged 5.75 credits per call

$ qveris inspect 1
icons
weather_gov.icons.retrieve.v3.ad0b4d80
Returns a forecast icon. Icon services in API are deprecated.

  Provider:   weather.gov
  Region:     global
  Latency:    ~325ms
  Success:    100.0%
  Billing:    Charged 5.75 credits per call

  Parameters:
    set  string  required
      .
    timeOfDay  string  required  The time of day for which to retrieve  data (e.g., "morning", "afternoon")

    first  string  required  The first record to retrieve (index or ID)

    size  string  optional
      Font size
    fontsize  integer  optional
      Font size

  Example:
    {"set":"land","first":"sct","timeOfDay":"day"}

$ qveris call 1 --params '{"set":"land","first":"sct","timeOfDay":"day"}'
✓ success  ·  311ms  ·  5.75 credits pre-settlement  ·  (1078.15 remaining)
tool: amap_webservice.weather.weatherinfo.retrieve.v3  ·  id: d79cd15b-2f36-4ce1-bb3c-6ea28b5ecfa2

Billing:
  Total estimated pre-settlement charge: 5.75 credits
  Pre-settlement: 5.75 credits
Final charge status: qveris usage --mode search --execution-id d79cd15b-2f36-4ce1-bb3c-6ea28b5ecfa2

{
  "status": "1",
  "count": "1",
  "info": "OK",
  "infocode": "10000",
  "lives": [
    {
      "province": "北京",
      "city": "东城区",
      "adcode": "110101",
      "weather": "多云",
      "temperature": "31",
      "winddirection": "西南",
      "windpower": "≤3",
      "humidity": "50",
      "reporttime": "2026-05-13 13:33:58",
      "temperature_float": "31.0",
      "humidity_float": "50.0"
    }
  ]
}

Install#

One-liner (recommended):

# Linux / macOS
curl -fsSL https://qveris.ai/cli/install | bash
 
# Windows (PowerShell)
irm https://qveris.ai/cli/install.ps1 | iex

Or via npm:

npm install -g @qverisai/cli

Or run without installing:

npx @qverisai/cli discover "stock price API"

Requires Node.js 18+.

Quick Start#

# Guided path: auth → discover → inspect → call → usage/ledger guidance
qveris init
 
# Manual path
# 1. Authenticate
qveris login
 
# 2. Discover capabilities
qveris discover "weather forecast"
 
# 3. Inspect a tool (by index from discover results)
qveris inspect 1
 
# 4. Call it
qveris call 1 --params '{"set":"land","first":"sct","timeOfDay":"day"}'

Commands#

Core#

Account#

Utilities#

Usage#

Init#

Run the guided first-call wizard:

qveris init
qveris init --query "weather forecast API"
qveris init --dry-run
qveris init --resume --params '{"city": "London"}'
qveris init --json

init discovers a capability, inspects the selected result, calls it with sample parameters when available, and ends with exact usage / ledger commands so you can reconcile final billing. Use --resume after recoverable parameter or provider failures to reuse the last discovery session.

Discover#

Search for capabilities using natural language. Each result shows the tool name, provider, tool ID, description, and quality metrics to help you choose.

qveris discover "stock price API"
qveris discover "translate text" --limit 10
qveris discover "weather forecast" --view routing --lang en

--view routing returns compact routing cards. --view full or omitting the flag preserves the existing complete response.

Inspect#

View full details of a tool before calling it. Shows parameters with types, required/optional, descriptions, allowed values (enum), and example parameters.

# By index (from last discover)
qveris inspect 1
 
# By tool ID
qveris inspect alphavantage.quote.execute.v1
 
# Inspect multiple tools
qveris inspect 1 2 3

Probe#

Validate candidate parameters and request a zero-cost quote without executing the capability:

qveris probe 1 --params '{"symbol":"AAPL"}' --checks schema,quote

schema and quote are implemented. coverage and sample can return an explicit unknown verdict. Probe never executes the capability or consumes credits.

Call#

Execute a tool. Results are automatically truncated for terminal display (4KB). Large results get an OSS download link. Billing shown here is pre-settlement; use qveris usage or qveris ledger for final charge status.

# Inline params
qveris call 1 --params '{"symbol": "AAPL"}'
 
# From file
qveris call 1 --params @params.json
 
# From stdin
echo '{"symbol": "AAPL"}' | qveris call 1 --params -
 
# Dry run (validate without executing, no credits consumed)
qveris call 1 --params '{"symbol": "AAPL"}' --dry-run
 
# Full result (no truncation)
qveris call 1 --params '{"symbol": "AAPL"}' --max-size -1
 
# Compact schema/size summary with a signed full-content URL
qveris call 1 --params '{"symbol": "AAPL"}' --respond-with summary
 
# Select fields rooted at result.data
qveris call 1 --params '{"symbol": "AAPL"}' --respond-with 'fields:$.price,$.currency'
 
# Generate code snippet after 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

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 are not downgraded and remain 422 errors.

Response Truncation#

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

• A preview of the truncated content
• A download link (valid 120 minutes) for the full result
• The response schema so you know the data structure

✓ success  ·  1200ms  ·  5 credits pre-settlement

Response truncated (32KB → 4KB preview)

Full content (valid 120 min):
  https://qveris-tool-results-cache-bj.oss-cn-beijing...
  Download: curl -o result.json '<url>' (Linux/macOS)
  Download: Invoke-WebRequest -Uri '<url>' -OutFile result.json (Windows PowerShell)

Schema:
  query: string
  total_results: number
  articles: array of
    pmid: string
    title: string

Preview:
  {"query": "evolution", "total_results": 890994, ...

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

MCP Configuration#

Generate MCP client config without hand-editing JSON. Print mode is the default and uses YOUR_QVERIS_API_KEY placeholders so the output is safe to share. Placeholder output intentionally fails API key validation until you replace it or use --include-key. For Claude Code, the command prints a claude mcp add command instead of writing a config file.

# Print safe config for Cursor
qveris mcp configure --target cursor
 
# Write a working Cursor config using your resolved API key
qveris mcp configure --target cursor --write --include-key
 
# Other supported targets
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

Config file locations and destinations:

• Cursor: ~/.cursor/mcp.json (Linux/macOS) or %USERPROFILE%\.cursor\mcp.json (Windows)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Claude Code: no config file is written; qveris mcp configure --target claude-code outputs a claude mcp add command

Validate an existing config:

# Static config validation
qveris mcp validate --target cursor
 
# Live stdio probe: starts the MCP server and confirms discover/inspect/probe/call are visible
qveris mcp validate --target cursor --probe

Supported targets: cursor, claude-desktop, claude-code, opencode, openclaw, generic.

Usage Audit#

Use qveris usage to answer whether recent calls succeeded, failed, or charged credits. It defaults to summary mode to protect Agent context. Summary mode requests service-side summary=true aggregates when available and falls back to bounded client-side aggregation for older deployments.

# Aggregate recent usage by hour/day/week
qveris usage --mode summary --bucket hour
 
# Check one execution precisely
qveris usage --mode search --execution-id <execution_id> --json
 
# Find high-cost or suspicious records
qveris usage --mode search --min-credits 30 --max-credits 100 --json
qveris usage --mode search --charge-outcome failed_charged_review --json
 
# Export raw matching rows to a local JSONL file instead of stdout
qveris usage --mode export-file --start-date 2026-05-01 --end-date 2026-05-04

Credits Ledger#

Use qveris ledger to explain final credit balance movements. It also 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 --mode summary --bucket day
qveris ledger --mode search --direction consume --min-credits 50 --json
qveris ledger --mode search --entry-type consume_tool_execute --json
qveris ledger --mode export-file --start-date 2026-05-01 --end-date 2026-05-04

summary and search never print full history. Large record sets are written to .qveris/exports/*.jsonl with --mode export-file.

Interactive Mode#

$ qveris interactive
 
qveris> discover "weather API"
Found 3 capabilities matching your query
1. openweathermap.weather.current.v1  by OpenWeather
   ...
 
qveris> inspect 1
openweathermap.weather.current.v1
  Parameters:
    city  string  required
    ...
 
qveris> call 1 '{"city": "London"}'
✓ success  ·  200ms  ·  2 credits
{ "temp": 18.5, ... }
 
qveris> codegen curl
curl -sS -X POST "https://qveris.ai/api/v1/tools/execute?tool_id=..." ...
 
qveris> exit

Configuration#

API Key#

# Option 1: Login (saves to the qveris config file)
qveris login
 
# Option 2: Environment variable
# Linux / macOS
export QVERIS_API_KEY="sk-1_..."
 
# Windows (PowerShell)
$env:QVERIS_API_KEY="sk-1_..."
 
# Windows (CMD)
set QVERIS_API_KEY=sk-1_...
 
# Option 3: Per-command flag
qveris discover "weather" --api-key "sk-1_..."

Resolution order: --api-key flag > QVERIS_API_KEY env > config file

API Endpoint#

The CLI uses a built-in API endpoint by default. When an explicit endpoint is required, set QVERIS_BASE_URL to the complete API root supplied by your QVeris service, or pass --base-url for one command.

# Reuse an endpoint supplied by your environment
qveris discover "weather" --base-url "$QVERIS_BASE_URL"

Resolution order: --base-url > QVERIS_BASE_URL > stored OAuth session endpoint (when OAuth is active) > built-in default. API keys never change the selected endpoint. Values must be complete HTTP(S) URLs without credentials, query parameters, or fragments; trailing slashes are normalized automatically.

Rate limiting & retries#

Rate-limited (429) and transient (503) responses are retried automatically: the CLI honors the Retry-After header when present, otherwise backs off exponentially with jitter. Retries default to 3 and are bounded so a command never hangs.

# Tune or disable via env
export QVERIS_MAX_RETRIES=5   # default 3; 0 disables

Config File#

Located at:

• All platforms: $XDG_CONFIG_HOME/qveris/config.json when XDG_CONFIG_HOME is set
• Default: ~/.config/qveris/config.json (for example, C:\Users\<user>\.config\qveris\config.json on Windows)

qveris config list          # View all settings with sources
qveris config set key value # Set a value
qveris config get key       # Get a value
qveris config path          # Print config file location
qveris config reset         # Reset to defaults

Shell Completions#

# Bash
eval "$(qveris completions bash)"
 
# Zsh
eval "$(qveris completions zsh)"
 
# Fish
qveris completions fish | source

Global Flags#

Agent / LLM Integration#

When used by agents or in scripts, the CLI auto-detects non-TTY environments:

# Agent workflow: discover → select → call → parse
 
# Linux / macOS
TOOL=$(qveris discover "weather" --json | jq -r '.results[0].tool_id')
qveris call "$TOOL" --params '{"city":"London"}' --json | jq '.result.data'
 
# Windows (PowerShell)
$TOOL = qveris discover "weather" --json | ConvertFrom-Json | Select-Object -ExpandProperty results | Select-Object -First 1 | Select-Object -ExpandProperty tool_id
qveris call $TOOL --params '{"city":"London"}' --json | ConvertFrom-Json | Select-Object -ExpandProperty result | Select-Object -ExpandProperty data
 
 # Windows (CMD, interactive) - requires jq for Windows
for /f "tokens=*" %i in ('qveris discover "weather" --json ^| jq -r ".results[0].tool_id"') do set TOOL=%i
qveris call %TOOL% --params "{\"city\":\"London\"}" --json | jq ".result.data"
 
# Windows (.bat/.cmd script) - use %%i instead of %i
for /f "tokens=*" %%i in ('qveris discover "weather" --json ^| jq -r ".results[0].tool_id"') do set TOOL=%%i
qveris call %TOOL% --params "{\"city\":\"London\"}" --json | jq ".result.data"

Exit Codes#

Zero Dependencies#

QVeris CLI uses only Node.js built-in APIs. No chalk, no commander, no yargs. Installs instantly via npx.

Links#

• Website: https://qveris.ai
• API Docs: https://qveris.ai/docs
• Get API Key: https://qveris.ai/account?page=api-keys
• GitHub: https://github.com/QVerisAI/qveris-agent-toolkit

License#

MIT