CLI 参考

pikeway setup

给 agent 用的一步配置:对比 CLI 与网关 skill 的版本、保存并校验 key、为你的客户端安装 skill 文件,并打印 MCP 接入命令。

用法

bash

pikeway setup [--key pk-...] [--label main] [--client claude-code|codex|opencode|<other>]
              [--skill-dir <dir>] [--no-skill] [--json]

说明

setup 按顺序做四项检查,并逐项报告结果。可以随时重复运行;仅仅缺少某项配置并不会让它失败。

版本。从网关下载 /SKILL.md,把其中的 version: 与 CLI 版本比较。CLI 较旧时会打印用于更新的 npm install -g … 命令。连不上网关时跳过此步。
Key。传入 --key 时,先用 GET /v1/auth/whoami 校验,通过后以 --label 为标签保存为当前 key。不传时,校验你已有的 key(PIKEWAY_API_KEY 或已保存的当前 key)。
Skill。把下载的 SKILL.md 写入客户端的 skills 目录(由 --client 或 --skill-dir 决定),否则提示你自行保存的位置。
MCP。打印把 Pikeway MCP 服务加入客户端的命令。这一步可选,不接 MCP 也能使用 CLI 和 skill。

参数

--key, -kpk-…

要校验并保存的 key。格式须为 pk- 加至少 8 个 A–Z a–z 0–9 _ - 字符。可在 /console/keys 创建。

--labelstring

保存 key 时使用的标签,默认 main。与 keys add 不同,同名的已有 key 会被替换。仅在传入 --key 时生效。

--clientstring

你的 agent 客户端(不区分大小写)。claude-code 或 claude:skill 保存到 ~/.claude/skills/pikeway/SKILL.md。codex:保存到 ~/.codex/skills/pikeway/SKILL.md。opencode:没有 skill 目录,但会给出对应的 MCP 说明。其他值(如 cursor)只给通用提示。

--skill-dirpath

改为把 SKILL.md 写入该目录(不存在时自动创建),优先于 --client。

--no-skillboolean

不写入 skill 文件,也不打印 skill 提示。

示例

bash

# first run in Claude Code: save the key, install the skill, get the MCP command
pikeway setup --key pk-AbCdEf0123456789xYz9 --client claude-code

# Codex, saving the key under another label
pikeway setup --key pk-... --label work --client codex

# just check that the CLI is current and the saved key still works
pikeway setup --no-skill

# put the skill in a project-local rules folder
pikeway setup --skill-dir ./.agents/skills/pikeway

# machine-readable report for an agent
pikeway setup --client claude-code --json

输出

一切正常

✓ pikeway 0.2.0 · skill 0.2.0
✓ key ok ([email protected])
✓ skill saved to /home/me/.claude/skills/pikeway/SKILL.md
MCP (optional): claude mcp add --transport http pikeway https://gw.pikeway.ai/mcp/agent

CLI 过旧、尚无 key、未指定客户端

! pikeway 0.1.0 · skill 0.2.0  → update: npm install -g https://gw.pikeway.ai/sdk/pikeway-cli.tgz
! no API key yet: create one at https://gw.pikeway.ai/console/keys, then: pikeway setup --key pk-…
! save https://gw.pikeway.ai/SKILL.md into your client's skills / rules directory so it loads next session
MCP (optional): https://gw.pikeway.ai/mcp/agent  (MCP with sign-in; or https://gw.pikeway.ai/mcp with an Authorization: Bearer pk-… header)

已保存的 key 被拒绝时,第二行显示 ! saved key is invalid: create one at …。--client codex 的 MCP 行为 codex mcp add pikeway --url https://gw.pikeway.ai/mcp/agent;opencode 则说明 opencode.json 的写法和 opencode mcp auth pikeway。

--json

json

{
  "cli": "0.2.0",
  "base": "https://gw.pikeway.ai",
  "skill": "0.2.0",
  "upToDate": true,
  "key": "ok",
  "account": "[email protected]",
  "skillPath": "/home/me/.claude/skills/pikeway/SKILL.md",
  "mcp": "claude mcp add --transport http pikeway https://gw.pikeway.ai/mcp/agent"
}

cli · basestring

CLI 版本和所连接的网关。

skillstring | null

网关 SKILL.md 中的版本号;无法获取时为 null。

upToDate · updateboolean · string

只有 upToDate 为 false 时才会出现 update(安装命令)。

key · account"ok" | "missing" | "invalid"

只有 key 为 ok 时才会出现 account(邮箱、钱包地址或用户 id)。

skillPath | skillHintstring

skill 的写入位置;未写入时给出提示。使用 --no-skill 时两者都不出现。

mcpstring

对应客户端的 MCP 命令或地址。

错误与退出码

缺少 key 或已保存的 key 无效只会被报告,不算错误,setup 仍以 0 退出。只有传入的 --key 有问题才会失败:

退出码	错误信息	触发条件
2	that does not look like a Pikeway key (pk-…)	`--key` 的值不符合 key 格式,不会保存任何内容。
3	key rejected: invalid or revoked API key	网关拒绝了 `--key` 的值,不会保存任何内容。
1	cannot reach <gateway>: ECONNREFUSED	无法连接网关(DNS、网络,或 PIKEWAY_API_BASE_URL 写错)。冒号后的错误码来自 Node。

升级 CLI 后请重新运行 pikeway setup,让 skill 文件与新版本保持一致。见 Skill 快速开始。

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