# CLI 命令行接入

用零第三方运行依赖的Node命令查看公开合同、账户、用量和模拟回执；显式执行开关才调用本地模拟数据。

从终端发现接口、检查余额，再读取一次调用的状态与结果。每条命令输出JSON，执行由明确的参数触发。

运行范围：NODE CLI · LOCAL ONLY

## 对应能力

- [获取 X 账号资料](https://datanavoapi.com/apis/x/users/get/)：x.users.get，返回 data.item，不支持分页，客户成功请求1 TEST。

## 保留完整项目，启动本机网站

在DataNavoAPI项目目录运行npm run local，再在另一终端运行node scripts/cli.mjs help。CLI使用Node内置功能并复用本地SDK，无需另装npm CLI包。

主机固定127.0.0.1，端口默认4321。可通过--port或GUANLIU_CLI_PORT修改端口，命令行参数优先。CLI自身不读取.env，也不保存配置。

## 先查公开合同，无需客户Key

这些命令只读取能力、对象、任务模板和配置状态。find沿用平台别名，仅搜索实际能力，不采集来源内容。

tasks返回三个已有工作流模板说明，不运行任务；status只反映本机开关配置，不探测供应商可用性。

```
node scripts/cli.mjs help
node scripts/cli.mjs find --query '小红书 评论'
node scripts/cli.mjs describe --capability x.users.get
node scripts/cli.mjs objects
node scripts/cli.mjs tasks
node scripts/cli.mjs status
```

[公开搜索合同](https://datanavoapi.com/v1/search)

[对象合同](https://datanavoapi.com/v1/objects)

[错误合同](https://datanavoapi.com/v1/errors)

## 从进程环境读取客户Key

在自己的本机进程环境中设置GUANLIU_CUSTOMER_API_KEY。不要把完整Key写进命令行参数、URL或共享脚本；CLI不提供--key选项。

account读取共享钱包与预算，usage只列当前Key用量，calls只列该Key模拟执行。客户查询始终simulated，无需--execute，也不产生预留或扣点。

```
node scripts/cli.mjs account
node scripts/cli.mjs usage --status all --page 1 --page-size 20
node scripts/cli.mjs calls --state all --page 1 --page-size 20
```

[创建客户Key](https://datanavoapi.com/account/keys/)

## 读取报价，核对单次TEST上限

quote是只读请求，不执行数据接口。eligible=false表示当前余额、预算、权限或上限条件不允许执行；报价不会锁定额度。

```
node scripts/cli.mjs quote --capability x.users.get --params '{"username":"guanliu_demo"}' --max-credits 1
```

## 显式开关才发起一次模拟执行

call必须同时提供--execute和--idempotency-key，缺少任一项会在网络请求前拒绝。参数通过--params JSON传入，只接受能力合同字段；场景仅success、failure、timeout。

此示例是新逻辑请求，使用前为自己的任务选择并保存编号。相同参数、场景和编号重放不新增扣点；新任务或下一页才使用新编号。真实API与支付没有CLI入口。

```
node scripts/cli.mjs call --capability x.users.get --params '{"username":"guanliu_demo"}' --execute --idempotency-key cli-account-sample-001 --scenario success --max-credits 1
```

## 用request_id查询回执与已保存结果

把下面UUID占位符替换为call响应中的request_id。receipt/result使用只读GET，不是重放call；不执行、不续租、不扣点。

result外层status=200表示读取成功，body.data.response.status可能为原执行的502或504。pending没有保存结果时返回409，不自动轮询。

```
node scripts/cli.mjs receipt --request-id 'REQUEST_UUID'
node scripts/cli.mjs result --request-id 'REQUEST_UUID'
```

[网页回执检查](https://datanavoapi.com/tools/request-inspector/)

[账户执行工作台](https://datanavoapi.com/account/executions/)

## 每次翻页都是明确的新请求

read-more要求原capability、原params（不含cursor）、--cursor、--execute及该页的--idempotency-key。它接受API返回的page.next_cursor，不接受MCP分页令牌。

每次指定--max-credits与原scenario；CLI不保存前一页上下文，也不替你生成编号或连续翻页。无分页能力会被拒绝。

## 让脚本保留HTTP状态与未知结果

stdout为单个JSON对象，默认即JSON；--json可显式注明。HTTP响应包含command、status、body、outcomeUnknown；参数或运输错误只在stderr输出安全错误JSON。

退出码0为HTTP读取成功或执行202，202仍不是执行完成；1为HTTP/传输/协议失败；2为参数、Key配置或缺少执行开关。客户执行运输失败outcomeUnknown=true；只读失败始终false。

CLI不自动重试或翻页，不把底层错误、认证头或完整Key写进输出。未知参数、重复选项、任意URL及非法端口均拒绝。

## 核对已经保存的真实请求

v0.28 增加明确的 live 只读入口。JavaScript / Python 使用 GuanliuLiveReadClient；CLI 使用 --mode live；stdio MCP 使用 GUANLIU_MCP_MODE=live。默认模拟模式保持原行为。

只读取当前 gl_live_ Key 的账户免费授权、用量、回执与保存结果。MCP 仅提供 find、describe、account，account 的 what=balance/usage/calls/standing/receipt/result；不执行新的请求，也不充值或支付。

pending 与 unknown 不自动重试。免费预留按供应商和单位分开，实际供应商成本未知；同账户其他 Key 占用幂等编号时不泄露其回执。

[live 只读接入说明](https://datanavoapi.com/mcp/#live-read)

[账户真实调用记录](https://datanavoapi.com/account/live-usage/)

## 下一步

[JavaScript SDK](https://datanavoapi.com/integrations/javascript/)

[Python SDK](https://datanavoapi.com/integrations/python/)

[MCP stdio](https://datanavoapi.com/integrations/mcp-stdio/)

[全部公开合同](https://datanavoapi.com/catalog.json)

真实API和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。

## 机器接入与数据说明

演示固定返回虚构样本，请检查 meta.mode，不得作为实时市场事实。MCP 默认 demo，可显式配置客户 Key 使用 simulated；SDK 固定模拟模式。模拟调用只消耗 TEST_CREDIT，真实供应商和支付保持关闭。

[能力合同](https://datanavoapi.com/catalog.json)

[OpenAPI](https://datanavoapi.com/openapi.json)

[Agent 指引](https://datanavoapi.com/agents.md)
