QVeris CLI

QVeris 能力路由网络的官方命令行工具。直接在终端或智能体框架中发现、检查和调用 10,000+ 真实已验证的 API 能力。

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

为什么用 CLI？ MCP 会将工具结构注入每轮 LLM 提示词（每个工具消耗数百 token），而 CLI 作为子进程执行 — 零提示词 token、确定性输出、即时启动。

安装#

一键安装（推荐）#

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+
• 零运行时依赖（仅使用 Node.js 内置 API）

快速开始#

# 引导式首次调用
qveris init
 
# 手动流程
# 1. 认证（保存到 ~/.config/qveris/config.json）
qveris login
 
# 2. 发现工具
qveris discover "天气预报 API"
 
# 3. 检查工具（使用 discover 结果的索引）
qveris inspect 1
 
# 4. 调用
qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'

命令#

qveris init#

引导式首次调用向导：解析认证、发现能力、检查能力、执行调用，并在最后给出 usage/ledger 对账命令。

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 @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'

投影参数仅在显式指定时发送。如果旧服务明确把投影字段判定为未知字段，CLI 只移除该字段并重试一次；无效投影仍按 422 错误返回。

试运行（不消耗积分）：

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 分钟后过期。用 qveris history 查看，qveris history --clear 清除。

智能体 / LLM 集成#

CLI vs MCP#

智能默认值#

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

脚本示例#

# 发现 → 提取工具 ID → 调用 → 解析结果
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'

退出码#

遵循 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 18+ 内置 API。没有 chalk、commander、yargs。

链接#

• 官网：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密钥