Quick first run#

New to QVeris? With your QVERIS_API_KEY set (create one at qveris.ai), 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.

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.