/qveris-cli

name: qveris-cli
description: "Use QVeris CLI to find and call third-party professional data and tools when existing tools are insufficient, a provider is unknown, comparison or fallback is needed, or the user requests QVeris."

Quick first run

New to QVeris? With your `QVERIS_API_KEY` set (create one at [qveris.ai](https://qveris.ai/account?page=api-keys)), `init` is a client-side first-call wizard: auth, discover, inspect, a real call, and exact usage/ledger commands to reconcile billing. It is not a server-side aggregate API.

export QVERIS_API_KEY="sk-..."
npx @qverisai/cli init

Re-run anytime with `--query "..."` to target a different capability, or `--dry-run` to validate without consuming credits. Once you've seen the loop, the commands below are the day-to-day surface.

Commands

# Discover tools by capability
qveris discover "weather forecast API" --json --limit 10

# Call after selecting result 1 because its contract matches these exact fields
qveris call 1 --params '{"wfo": "BOU", "x": 50, "y": 30}' --json

# Inspect only when selection/request construction needs missing or stale details
qveris inspect 1 --json

# Probe only for parameter validation or a current quote; it does not reserve a price
qveris probe 1 --params '{"wfo": "BOU", "x": 50, "y": 30}' --checks schema,quote --json

# Validate without consuming credits
qveris call 1 --params '{"wfo": "BOU", "x": 50, "y": 30}' --dry-run --json

# Generate production code snippet (curl/python/js) — only on successful calls
qveris call 1 --params '{"wfo": "BOU", "x": 50, "y": 30}' --codegen curl

**Always use `--json`** for structured output.

---

Response Size

Default: 4KB (TTY) / 20KB (piped/`--json`). Use `--max-size -1` for unlimited. Large responses are auto-truncated with a download link for the full result.

---

Session Mechanism

The CLI saves the last Discover ID, query, endpoint, and result summaries for 30 minutes. This supports numeric indices and real discovery attribution; it is not semantic routing memory or a complete schema cache. A new Discover replaces the indices. Use `qveris history --clear` to clear it.

Build parameters from the selected capability's current contract and the user's current request. An explicit empty contract is a zero-parameter tool; an omitted contract requires Inspect. Do not copy sample business values, drop required/enum/one-of constraints, or reuse a previous entity/date value.

For provider comparison, Inspect every candidate when current scope or a complete contract must be confirmed; a Discover summary is not confirmation. Probe every candidate when the comparison requires a current quote. Reuse may preserve an exact route, never business parameters or results: build parameters from the current request, and make a fresh Call for current, latest, today, or other time-sensitive data.

---

Discover Query Formulation

**Describe tool capability, not data you want.**

| User request | Wrong | Correct | |-------------|-------|---------| | "Nvidia earnings" | `"Nvidia earnings"` | `"company earnings report API"` | | "Beijing weather" | `"Beijing weather today"` | `"weather forecast API"` | | "BTC price" | `"what is BTC price"` | `"cryptocurrency price API"` |

Always query in English.

---

Tool Selection

Choose among connected tools and QVeris by task fit, data quality/freshness, cost, user constraints, and call overhead. Use QVeris when a capability is missing, the provider is unknown, comparison/fallback is needed, or the user requests it. Within Discover results, consider contract fit, provider/coverage constraints, quality, latency, and cost; do not select the first result solely by rank.

---

Error Recovery

Only retry when the response proves execution did not occur.

1. For a definite validation failure, fix parameters from the current contract or request missing input. 2. Drop optional parameters only if doing so preserves the user's requested meaning. 3. Switch to another compatible result only if provider, coverage, cost, and authorization constraints still hold.

Do not repeat a paid or side-effecting Call after a timeout, network failure, or unknown execution outcome. Report the uncertainty and audit by `execution_id` when available.