CLI 参考

CLI 概览

在终端或 agent 的 shell 工具里搜索、查看和调用按次付费的端点。单文件、无依赖,需要 Node 18+。

安装

CLI 还没有发布到 npm,请从本站安装:

bash

npm install -g https://<your-pikeway-site>/sdk/pikeway-cli.tgz
pikeway --version

也可以交给 agent:对它说 set up https://<your-pikeway-site>/SKILL.md,它会安装 CLI、保存 skill,并用 pikeway setup 检查你的 key。

快速上手

bash

pikeway discover -q "token price on solana"          # free, no key
pikeway inspect -p birdeye -e /defi/price            # input schema + price
pikeway keys add --label main --key pk-...           # from /console/keys
pikeway run -p birdeye -e /defi/price -i '{"address":"So11111111111111111111111111111111111111112"}'
pikeway runs list && pikeway balance

discover 和 inspect 免费,无需 key。凡是会花钱或读取账户信息的命令都需要 key。

配置

API key 的确定顺序

需要 key 的命令按以下顺序取第一个找到的 key:

命令行上的 --key pk-… / -k pk-…
环境变量 PIKEWAY_API_KEY
用 pikeway keys add / activate 保存的当前 key

设置了 PIKEWAY_API_KEY 时,它的优先级高于已保存的当前 key,此时 pikeway keys activate 看起来不起作用。要使用已保存的 key,请先 unset 它。

配置文件

保存的 key 位于 $XDG_CONFIG_HOME/pikeway/config.json(默认 ~/.config/pikeway/config.json)。目录以 700 权限创建,文件以 600 权限写入。key 以明文保存,请像对待密码一样保护该文件。

~/.config/pikeway/config.json

{
  "keys": [
    { "label": "main", "key": "pk-AbCdEf0123456789xYz9" },
    { "label": "ci", "key": "pk-9fQr7s6t5u4v3w2xT2mw" }
  ],
  "active": "main"
}

环境变量

PIKEWAY_API_KEYpk-…

代替已保存的当前 key 使用(--key 参数的优先级更高)。

PIKEWAY_API_BASE_URLURL

要连接的网关。默认是 CLI 内置的托管网关(https://gw.pikeway.ai);pikeway --help 会打印当前使用的地址。本站对应:https://gw.pikeway.ai。

XDG_CONFIG_HOMEpath

pikeway 配置目录的创建位置,默认 ~/.config。

NO_COLORany

关闭颜色。stdout 不是 TTY 时也会关闭颜色。

让 CLI 连接本站网关

export PIKEWAY_API_BASE_URL=https://gw.pikeway.ai
pikeway --help | head -1

全局参数

-j, --jsonboolean

输出原始 JSON 响应,而不是便于阅读的文本。

-k, --keypk-…

本条命令使用该 key(覆盖 PIKEWAY_API_KEY 和已保存的 key)。

-h, --help · helpboolean

打印用法、CLI 版本和当前网关。不带命令运行 pikeway 效果相同。

-v, --versionboolean

打印 CLI 版本后退出。

参数写法

参数值可以写成 --flag value 或 --flag=value。短参数取下一个参数作为值:-l 3。
短参数只有一个字母,不能合并:要写 -j -l 3,不能写 -jl 3。
布尔参数(--json、--async、--wait、--no-skill)不会吃掉下一个参数;写 --async=false 可关闭。
未知参数不会报错。拼错的带值参数(如 --limt 3)会被忽略并吃掉下一个参数,脚本里请仔细检查拼写。
-- 之后的内容都按位置参数处理。

JSON 输出

加上 -j / --json 后,每条命令都会在 stdout 上原样输出 API 响应体(格式化后的 JSON),不再打印 next:、more: 提示行和 stderr 上的状态行。keys 系列命令不连接网关,会输出一个描述本地改动的小对象。

bash

pikeway discover -q "token price on solana" --json | jq -r '.results[0].endpoint'
pikeway run -p birdeye -e /defi/price -i '{"address":"So111..."}' -j | jq '.output.data.value'
pikeway balance --json | jq '.spendable.value'

出错时会在 stdout 上输出一行 JSON,退出码与文本模式相同。details 是网关返回的错误体,没有时为 null:

json

{"error":"missing --provider","details":null}
{"error":"unknown endpoint /price on birdeye","details":{"code":404,"message":"unknown endpoint /price on birdeye","available":["GET /defi/history_price","GET /defi/price"]}}

只有命令行里出现字面上的 --json 或 -j 时,错误才会以 JSON 输出。写成 --json=true 时结果是 JSON,但错误仍是纯文本。

文本模式下,错误以 error: <message> 的形式输出到 stderr。

退出码

退出码	错误信息	触发条件
0	—	成功。
1	cannot reach <gateway>: … · <gateway message>	请求失败(网络错误、401/403 以外的 4xx/5xx),或 `pikeway run` 结束时状态不是 `COMPLETED`。
2	missing --provider · unknown command "x"	用法错误:缺少必填参数、`--input` 不是合法 JSON、未知命令或子命令,或本地 `keys` 冲突。
3	no API key: … · invalid or revoked API key	鉴权:找不到 key,或网关返回 401/403。