CLI 参考

pikeway run

调用端点并获取输出。默认同步执行,也可以用 --async / --wait 在后台运行。

用法

bash

pikeway run -p <provider> -e <endpoint> [-m <method>]
            [-i '<json>' | -i @input.json | -i -] [-o <file>]
            [--async [--timeout <s>] | --wait [--timeout <s>]]
            [--json] [--key pk-...]

说明

把调用发送到 POST /v1/run:网关按端点 schema 校验输入、调用上游 API、从余额扣费并返回结果。只有上游调用成功才会扣费。

状态行(状态、上游 HTTP 码、费用、耗时、run id)输出到 stderr,结果输出到 stdout,因此 pikeway run … | jq 只会拿到结果。字符串结果原样输出,JSON 结果会格式化。

只要运行状态不是 COMPLETED(例如 FAILED、STOPPED、TIMED_OUT),命令就以 1 退出,但结果(调用失败时为上游返回的错误内容)仍会输出。

少数耗时较长的端点在网关上总是后台运行,即使不加 --async。这类端点请使用 --wait(或 --async 后再用 pikeway runs get)。

参数

--provider, -pstring必填

API slug。

--endpoint, -estring必填

端点路径,模板或具体路径均可。

--method, -mstring

HTTP 方法。仅当该路径有多个方法时需要。

--input, -iJSON | @file | -

输入:直接写 JSON、@path/to/file.json,或 - 表示从 stdin 读取。默认 {}。见输入格式。

--output, -opath

把运行结果写入该文件,而不是 stdout。字符串原样写入,其他内容写成格式化 JSON。状态行仍输出到 stderr。

--asyncboolean

在后台启动运行,打印 run id 后立即返回。需要 key。

--waitboolean

在后台启动,然后轮询 GET /v1/runs/<id>,间隔从 0.5 秒开始翻倍,最长 8 秒,直到结束;最后像同步调用一样输出结果。需要 key。

--timeoutseconds

配合 --async / --wait:运行允许的最长时间。服务端默认 300,最大 900。同步运行时忽略。

输入格式

可以按位置拆分输入,也可以传一个扁平对象,由网关根据端点 schema 把每个字段放到路径参数、查询参数或 body 中。pikeway inspect 会列出有哪些字段,并给出可运行的示例。

按位置拆分

{ "pathParams": { "protocol": "aave" }, "queryParams": { "limit": 10 }, "body": { "range": "30d" } }

扁平对象

{ "address": "So11111111111111111111111111111111111111112" }

示例

bash

# inline JSON
pikeway run -p birdeye -e /defi/price -i '{"address":"So11111111111111111111111111111111111111112"}'

# input from a file, output to a file
pikeway run -p birdeye -e /defi/price -i @input.json -o out.json

# input from stdin
echo '{"address":"So11111111111111111111111111111111111111112"}' | pikeway run -p birdeye -e /defi/price -i -

# path parameter + pipe the output
pikeway run -p defillama -e /tvl/aave | jq .

# long job: start in the background and wait for it (up to 10 minutes)
pikeway run -p someapi -e /reports -m POST -i '{"body":{"range":"30d"}}' --wait --timeout 600

# fire and forget, check later with pikeway runs get
pikeway run -p someapi -e /reports -m POST -i '{"body":{"range":"90d"}}' --async

# use a specific key for this call only
pikeway run -p coingecko -e /simple/price -i '{"ids":"bitcoin","vs_currencies":"usd"}' -k pk-...

输出

同步调用

COMPLETED · HTTP 200 · cost $0.001 · 214ms · run 0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11
{
  "success": true,
  "data": { "value": 172.41, "updateUnixTime": 1761297120 }
}

第一行输出在 stderr。使用 -o 时结果写入文件,stderr 改为显示 output written to out.json。上游调用失败时如下(退出码 1,费用 $0):

text

FAILED · HTTP 400 · cost $0 · 188ms · run 0192f6af-11c4-7a0e-9b52-3d7e8f1a2c64
{
  "success": false,
  "message": "address is invalid"
}

--async

QUEUED · run run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87 · timeout 300s
check: pikeway runs get -r run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87   stop: pikeway runs stop -r run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87

--wait

  running…
COMPLETED · HTTP 200 · cost $0.01 · 41250ms · run run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87
{
  "range": "30d",
  "rows": 1240,
  "url": "https://…/report.csv"
}

等待期间,stderr 上会刷新一行 queued… / running… 进度提示。

--json

完整的运行对象,与 /v1/run 相同。--async 时是 202 响应体(runId、status: "QUEUED"、timeoutSeconds、pollUrl);--wait 时是最终的 GET /v1/runs/<id> 响应体。

json

{
  "runId": "0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11",
  "provider": "birdeye",
  "endpoint": "/defi/price",
  "method": "GET",
  "status": "COMPLETED",
  "output": { "success": true, "data": { "value": 172.41, "updateUnixTime": 1761297120 } },
  "providerResponse": { "httpStatus": 200, "contentType": "application/json", "cache": "" },
  "price": { "type": "PER_CALL", "amount": { "value": 0.001, "currency": "USD" } },
  "cost": { "value": 0.001, "currency": "USD" },
  "durationMs": 214,
  "hints": { "get": "curl -s https://gw.pikeway.ai/v1/runs/0192f6b0-… -H 'Authorization: Bearer $PIKEWAY_API_KEY'" }
}

错误与退出码

退出码	错误信息	触发条件
2	missing --provider · missing --endpoint	缺少必填参数。
2	--input must be JSON (or @file.json, or - for stdin)	`-i` 的内容无法解析为 JSON。
2	cannot read input.json: ENOENT	`@` 后面的文件不存在或无法读取。
3	no API key: run `pikeway keys add --label main --key pk-...`, set PIKEWAY_API_KEY, or pass --key	没有 --key、没有 PIKEWAY_API_KEY,也没有已保存的当前 key。在发出请求之前就会检查。
3	invalid or revoked API key — add a key with `pikeway keys add --label main --key pk-...` (or use --x402)	网关返回 401(key 不存在、已吊销或已过期)。403 同样以 3 退出。
1	missing required input	缺少必填的路径或查询参数。加 `--json` 时,`details.missing` 指出缺少的字段,`details.input` 给出 schema。
1	insufficient balance — top up your balance, or pay per call with --x402	余额(或 key 预算)低于本次调用价格。
1	unknown endpoint /price on birdeye	不存在该 API 或路径。
1	FAILED · HTTP 400 · …	运行结束时状态不是 `COMPLETED`。上游调用失败不扣费。
1	cannot reach <gateway>: ECONNREFUSED	无法连接网关(DNS、网络,或 PIKEWAY_API_BASE_URL 写错)。冒号后的错误码来自 Node。

同步运行的结果丢了?同步运行的结果不会被保存,pikeway runs get 只能看到状态和费用,看不到结果。需要保留时请使用 -o。

同样支持全局参数 -j, --json 和 -k, --key。见全局参数与退出码。