QVeris CLI

QVeris 专业数据与工具访问的官方命令行工具。直接在终端或智能体框架中发现服务、按需检查支持范围并调用。

进行 Provider 比较时，如果需要确认当前范围或完整契约，必须逐一 Inspect；Discover 摘要不等于确认。比较需要当前报价时，必须逐一 Probe。复用只能保留精确路由，不能保留业务参数或结果：参数必须来自当前请求；当前、最新、今天或其他时效性数据必须执行新的 Call。

@qverisai/cli v0.11.3 是最新测试版本，包含 OAuth Device Flow 会话、零成本参数校验与报价、可选的发现和调用投影及 Call 模型归因，同时保持 API Key 兼容。

为什么用 CLI？ CLI 通过子进程提供结构化输出和按需发现，无需预加载完整服务目录。使用说明、命令和结果仍会消耗上下文 token；QVeris MCP 同样提供紧凑的工具面。

安装

一键安装（推荐）

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

脚本自动检查 Node.js 18+，全局安装 @qverisai/cli，并添加到 PATH。

npm

npm install -g @qverisai/cli

npx（免安装）

npx @qverisai/cli discover "天气 API"

环境要求

• Node.js 18+
• 无必需的运行时依赖；系统凭据存储可选用 @napi-rs/keyring

快速开始

# 引导式首次调用
qveris init

# 手动流程
# 1. 认证（保存到 ~/.config/qveris/config.json）
qveris login

# 2. 发现工具
qveris discover "天气预报 API"

# 3. 按当前契约确认结果 1 接受这些字段后调用
qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'

# 可选：契约详情或当前报价有必要时再检查
qveris inspect 1
qveris probe 1 --params '{"wfo": "LWX", "x": 90, "y": 90}' --checks schema,quote

命令

qveris init

客户端首次调用向导：解析认证、发现并检查能力、执行调用，并在最后给出 usage/ledger 对账命令。这是 CLI onboarding 流程，不是服务端聚合接口。

qveris init [query] [flags]

示例：

qveris init
qveris init --query "股票价格 API"
qveris init --dry-run
qveris init --resume --params '{"city": "London"}'

最后一步会打印精确的 qveris usage 和 qveris ledger 命令，便于确认最终扣费结果。

qveris discover

使用自然语言搜索 API 能力。返回工具名称、提供商、ID、描述、相关性得分、成功率、延迟和计费规则摘要（如可用）。

qveris discover <query> [flags]

示例：

qveris discover "股票价格 API"
qveris discover "将文本翻译成法语" --limit 10
qveris discover "加密货币市场数据" --json
qveris discover "天气预报" --view routing --lang zh

每个工具的输出字段：

• 工具名称和提供商
• tool_id（用于 inspect/call）
• 描述
• 相关性得分、成功率、延迟、计费规则摘要
• 分类和区域（如适用）
• 执行历史标记（不代表正确性或可靠性认证）

qveris inspect

查看工具的完整详情。显示参数的类型、描述、枚举值、提供商信息和示例参数。

qveris inspect <tool_id|index> [flags]

数字索引（如 1、2）引用上一次 discover 的结果。

示例：

# 按索引
qveris inspect 1

# 按工具 ID
qveris inspect openweathermap.weather.current.v1

# 检查多个工具
qveris inspect 1 2 3

输出包含：

• 工具名称、ID、描述
• 提供商名称和描述
• 区域、延迟、成功率、计费规则
• 参数： 名称、类型、必填/可选、描述、允许值（枚举）
• 示例参数
• 最近执行记录（如有）

qveris probe

在不执行能力的情况下校验候选参数并获取零成本报价。

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

--checks 支持 schema、quote、coverage 和 sample；--live-budget 支持 none、metadata 和 sampled。当前契约已实现 schema 和 quote；coverage 与 sample 可能返回 unknown。Probe 不执行能力，也不消耗积分。

qveris call

执行一个能力。返回结构化结果、执行时间、预结算账单和剩余积分。最终是否扣费请通过 qveris usage 或 qveris ledger 查询。

qveris call <tool_id|index> [flags]

参数输入方式：

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

# 记录模型归因
qveris call 1 --params '{"city": "London"}' --model router-model-v1

# 从文件
qveris call 1 --params @params.json

# 复制的安装页上下文（不再传位置工具 ID 或旧 discovery ID）
qveris call --context @context.json --params @params.json

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

# 返回 schema、大小摘要和完整内容签名 URL
qveris call 1 --params '{"city": "London"}' --respond-with summary

# 选择以 result.data 为根的字段
qveris call 1 --params '{"city": "London"}' --respond-with 'fields:$.temperature,$.humidity'

投影参数仅在显式指定时发送。付费调用严格 single-submit：CLI 不会重试 429/503，不会跟随 HTTP 重定向，不会在 401 后刷新 OAuth 并重放，也不会删除被拒绝的投影字段后再次提交。投影拒绝和无效投影都按 422 错误返回。QVERIS_MAX_RETRIES 仅继续用于读和审计命令。

复制的服务/任务上下文

安装页可以复制只含公开选择 ID 和 Unix 秒时间戳的版本 1 JSON 模板。CLI 是该模板的权威消费者：

qveris call --context @context.json --params @params.json

--context 与位置工具 ID、--discovery-id 互斥。模板只是选择提示，不是参数、授权、可用性、价格或执行证明。参数必须根据当前用户请求另行传入。

执行 Call 前，CLI 会重新 Discover，并且只使用新的 search_id。有准确 tool 的上下文仅用 tool_id 作确定性查询；仅含 service 的上下文使用 task/service 意图，只返回刷新后的候选并停止，绝不猜测工具。Discover 若已给出完整参数合同即可完成参数预检；只有必要合同缺失时才 Inspect，只有 schema/参数、权限/价格、显式 --require-quote、预算上限或付费风险需要服务器确认时才 Probe。

过期只会让旧的可用性、价格和权限快照失效；安全任务意图和公开 ID 会被保留并自动刷新。任何已出现但非明确免费或含义不确定的价格信号（包括自然语言 expected_cost）都属于付费风险，必须取得结构合法的 credits 报价。Probe 报价不会锁定价格或授权执行，所以在精确 tool Context Call 的执行端点具备服务端预算字段前，--max-credits 会被拒绝。缺失副作用或幂等性元数据会产生 warning，并保持付费 Call 严格单次提交；只有明确报告的危险副作用或非幂等执行才要求对应确认参数。Context 校验采用有深度上限的迭代遍历，恶意深层嵌套会得到结构化拒绝，不会耗尽调用栈。

只要已发布合同能提供充分证明，CLI 就会自动完成安全恢复：旧发现会立即刷新，不完整 schema 会触发 Inspect，精确工具缺失会触发 service 重新发现。只有恰好一个当前候选明确报告相同 service_id 时才会自动 fallback；候选含糊或身份无法证明时仍要求选择。已提交的 Call 绝不自动重放。错误若包含 execution_id，CLI 会进行一次有界 Usage/Ledger 对账；没有最终记录时明确报告 unknown settlement。JSON 结果与失败统一包含稳定的 next_action 对象，智能体不需要理解内部 digest、evidence 或 version 细节。

普通未知字段会被忽略并返回 machine-readable warning。重复字段、原型污染键、疑似凭证、PII、提示词、raw payload 以及可能成为执行参数的字段会被严格拒绝。ID 长度必须为 1–128 个字符，以 ASCII 字母或数字开头，并且只能包含 ASCII 字母、数字、.、_、:、/ 或 -。

• 过期上下文： CLI 保留安全意图/公开 ID，并自动刷新当前候选和快照。
• 不支持/不安全的上下文： 升级以支持必需能力，或移除敏感/可执行内容；若凭证曾暴露，请轮换。
• 重新发现或检查不匹配： 选择当前结果，不要强制使用旧 ID。
• 验证或报价拒绝： 修正 --params、调整预算策略，或选择返回的 fallback 候选。报价不是锁价或执行授权。
• 权限或积分失败： 确认当前端点的账户/能力权限或积分。
• 上游失败或结算未知： 保留 execution_id；先运行 qveris usage --mode search --execution-id <id> 和 qveris ledger，再陈述最终扣费结果。

这条通用路径有意不定义主任务服务、计费规则、权限集、参数、预期结果或结算结果。这些信息必须来自另行批准的服务说明和当前 API 响应。

试运行（不消耗积分）：

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

代码生成：

# 调用成功后生成 curl、Python 或 JavaScript 代码片段
qveris call 1 --params '{"symbol": "AAPL"}' --codegen curl
qveris call 1 --params '{"symbol": "AAPL"}' --codegen python
qveris call 1 --params '{"symbol": "AAPL"}' --codegen js

响应截断

终端使用时（TTY），超过 4KB 的结果自动截断。CLI 会显示：

• 截断内容的预览
• OSS 下载链接（120 分钟有效）
• 响应的 JSON 结构，帮助理解数据结构
• 提示：使用 --max-size -1 获取完整输出

智能体/脚本场景（--json 或管道输出）默认提高到 20KB。用 --max-size -1 获取完整结果。

qveris mcp configure

为 Cursor、Claude Desktop、Claude Code、OpenCode、OpenClaw 或通用 stdio 客户端生成 MCP 配置。默认是打印模式，并使用 YOUR_QVERIS_API_KEY 占位符，因此输出可以安全粘贴到 issue 或文档中。占位符输出会故意无法通过 API key 校验，直到你替换占位符或使用 --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

支持的目标：

参数：

qveris mcp validate

校验 MCP 配置文件。静态校验会检查配置结构、QVeris 条目、API key 绑定方式，以及预期的规范工具。

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

添加 --probe 会启动配置中的 stdio MCP server，并通过 tools/list 确认 discover、inspect、probe、call 工具可见。

qveris mcp validate --target cursor --probe

--probe 需要可执行的 stdio 命令和真实的 QVERIS_API_KEY；OpenClaw 插件配置不支持该探测方式。

qveris auth login/status/logout

在本地或无头终端通过 OAuth Device Flow 登录，无需复制 API 密钥。CLI 从当前 API 站点的 Discovery 获取全部 OAuth 端点，打开验证页面，并严格按服务端返回的轮询间隔等待授权。

qveris auth login
qveris auth status
qveris auth logout

Refresh Token 会自动轮换并保存在操作系统凭证库中。系统凭证库不可用时，CLI 默认仅在当前进程保留凭证。在可信的无头主机上，可显式添加 --allow-unencrypted-storage，将 token 持久化到权限为 0600 的用户配置文件中。auth logout 会先尝试远程撤销，再清理本地凭证。显式配置的 API Key 继续保持原有优先级和行为。

持久化的 OAuth 会话还会记住其 API 地址，供后续 CLI 进程自动恢复。显式传入的 --base-url 或 QVERIS_BASE_URL 仍具有更高优先级，且必须与会话 issuer 匹配。

在没有操作系统凭证库的可信无头主机上，可使用 --no-browser --allow-unencrypted-storage。高级集成可通过 --scope <scopes> 和 --resource <url> 收窄授权请求；两者都必须符合服务端公开契约，且自定义 scope 必须保留 offline_access，以便安全刷新会话。

qveris login（API Key）

使用 QVeris API 密钥认证。打开浏览器进入 API 密钥页面并掩码输入。

qveris login [flags]

# 交互式（打开浏览器 → 掩码输入）
qveris login

# 非交互式
qveris login --token "sk-1_your-key-here"

密钥保存到 ~/.config/qveris/config.json，权限为 0600（仅所有者可读写）。

qveris logout

从配置中移除已存储的 API 密钥。

qveris whoami

显示当前认证状态、密钥来源，并验证密钥有效性。

qveris credits

查看剩余积分余额。

qveris usage

查询调用级使用审计，默认使用 summary 聚合模式，避免把大量流水直接输出到智能体上下文。 summary 模式会优先请求服务端 summary=true 聚合摘要；若旧部署暂不支持，则回退到有上限的客户端聚合。

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

常用过滤参数：--execution-id、--search-id、--charge-outcome、--min-credits、--max-credits、--start-date、--end-date。

qveris ledger

查询最终积分账本，默认使用 summary 聚合模式。 summary 模式会优先请求服务端 summary=true 聚合摘要；若旧部署暂不支持，则回退到有上限的客户端聚合。

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 会把原始记录写入 .qveris/exports/*.jsonl，只返回文件路径和记录数，不直接打印全量记录。

qveris interactive

启动 REPL 会话，支持链式 discover/inspect/call 工作流。会话状态保存在内存中并持久化到磁盘。

qveris interactive [flags]

别名：qveris repl

REPL 命令：

qveris> discover "加密货币价格 API"
qveris> inspect 1
qveris> call 1 {"symbol": "BTC"}
qveris> codegen python
qveris> exit

qveris doctor

面向首次调用的自检诊断：依次检查 Node.js 版本、当前 API Key 或 OAuth 会话、API 地址，再用一次免费的 discover 探测覆盖连通性、凭证有效性、剩余积分，以及响应结构是否符合 CLI 合同。每项失败都会给出可执行的修复建议。诊断不消耗积分（discover 免费）。加 --json 输出机器可读结果。

qveris config

管理 CLI 设置。

qveris config <subcommand> [args]

配置项： api_key, default_limit, default_max_size, color, output_format

qveris completions

生成 Shell 自动补全脚本。

# Bash
eval "$(qveris completions bash)"

# Zsh
eval "$(qveris completions zsh)"

# Fish
qveris completions fish | source

qveris history

显示当前会话状态（上次查询、结果、时间）。

qveris history [--clear]

全局参数

所有命令通用：

支持 --key=value 语法和组合短参数（-jv）。

用 -- 结束选项解析：qveris discover -- --literal-query。

环境变量

优先级： --flag > 环境变量 > 配置文件 > 默认值

API 地址单独遵循 --base-url > QVERIS_BASE_URL > 已存储的 OAuth 会话地址（OAuth 生效时）> 内置默认值。API 密钥不会选择或替换地址。覆盖值必须是完整的 HTTP(S) URL，且不能包含凭据、查询参数或片段。

会话管理

每次 discover 后，CLI 将会话状态保存到 ~/.config/qveris/.session.json：

• 发现 ID
• 查询内容
• API 地址
• 不包含秘密的授权上下文绑定
• 结果列表（tool_id、名称、提供商）

后续 inspect 和 call 自动读取会话，支持数字索引快捷方式：

qveris discover "weather API"    # 保存会话
qveris inspect 1                  # 使用会话中的索引 1
qveris call 2 --params '{...}'   # 使用索引 2 + 发现 ID

会话 30 分钟后过期。只有当前 API 地址和授权上下文与创建会话时精确匹配，数字索引、隐式 Discovery ID 和 init --resume 才可使用。切换地址或账号后必须重新 Discover。用 qveris history 查看，qveris history --clear 清除。

这里保存的是最近一次 Discover 的索引和来源信息，不是语义意图路由或完整 schema 缓存。新的 Discover 会覆盖旧索引。每次 Call 都要根据当前请求重新构造业务值；如果会话摘要不含安全构造请求所需契约，应先 Inspect。

智能体 / LLM 集成

应根据任务适配度、数据质量/时效、费用、用户约束和调用开销，在已连接工具与 QVeris 之间选择。能力缺失、Provider 未知、需要跨 Provider 比较或 fallback，或用户明确指定 QVeris 时，QVeris 尤其适合。QVeris 内部默认使用 discover → call；只有选择或合法构造请求所需契约缺失/过期时才 inspect，只有参数校验或预算决策需要当前报价时才 probe。报价不等于锁价或授权。

CLI vs MCP

智能默认值

CLI 自动检测智能体与人类使用场景：

脚本示例

# Discover 一次，再按返回契约选择，不能只取首个结果
DISCOVERY=$(qveris discover "weather forecast API" --json)
TOOL=$(printf '%s' "$DISCOVERY" | jq -r '.results[] | select(.params != null and ([.params[].name] | index("city")) != null and ([.params[] | select(.required == true) | .name] - ["city"] | length == 0)) | .tool_id' | head -1)
SEARCH_ID=$(printf '%s' "$DISCOVERY" | jq -r '.search_id')
test -n "$TOOL" || { echo "需要 Inspect：Discover 未返回 city 参数契约" >&2; exit 1; }
qveris call "$TOOL" --discovery-id "$SEARCH_ID" --params '{"city":"London"}' --json | jq '.result.data'

退出码

遵循 BSD sysexits.h 规范：

旧命令兼容

以下别名支持向后兼容（会显示弃用警告）：

架构

@qverisai/cli
├── bin/qveris.mjs           # 入口
├── src/
│   ├── main.mjs              # 命令分发 + 参数解析
│   ├── commands/              # 12 个命令处理器
│   ├── client/api.mjs         # HTTP 客户端（原生 fetch）
│   ├── client/auth.mjs        # API 密钥解析
│   ├── config/endpoint.mjs    # API 地址解析
│   ├── config/store.mjs       # 配置文件读写（0600 权限）
│   ├── session/session.mjs    # 会话持久化
│   ├── output/formatter.mjs   # 人类友好格式化
│   ├── output/codegen.mjs     # 代码片段生成
│   └── errors/handler.mjs     # 错误处理 + BSD 退出码
└── scripts/install.sh         # 一键安装脚本

无必需的运行时依赖。 核心命令使用 Node.js 内置 API；需要 Node.js 18.2.0 或更高版本。OAuth 凭据存储可选用 @napi-rs/keyring。

链接

• 官网：QVeris 官网
• GitHub：QVerisAI/qveris-agent-toolkit
• npm：@qverisai/cli
• REST API：docs/zh-CN/rest-api.md
• MCP 服务器：docs/zh-CN/mcp-server.md
• 获取 API 密钥：控制台/API密钥