CLI Reference

pikeway setup

One-step setup for agents: check the CLI version against the gateway's skill, save and verify a key, install the skill file for your client, and print the MCP command.

Synopsis

bash

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

Description

setup runs four checks in order and reports each one. It is safe to run again at any time; it never fails just because something is missing.

Version. Downloads /SKILL.md from the gateway and compares its version: with the CLI's. If the CLI is older, it prints the npm install -g … command to update. If the gateway can't be reached, this step is skipped.
Key. With --key, the key is checked against GET /v1/auth/whoami and, if accepted, saved as the active key under --label. Without it, the key you already have (PIKEWAY_API_KEY or the saved active key) is verified.
Skill. Writes the downloaded SKILL.md into your client's skills directory, chosen by --client or --skill-dir. Otherwise it tells you where to save it.
MCP. Prints the command that adds the Pikeway MCP server to your client. This step is optional; the CLI and skill work without it.

Options

--key, -kpk-…

Key to verify and save. Must look like pk- followed by at least 8 of A–Z a–z 0–9 _ -. Create one at /console/keys.

--labelstring

Label to save the key under. Default main. Unlike keys add, an existing key with the same label is replaced. Only used with --key.

--clientstring

Your agent client (case-insensitive). claude-code or claude: skill goes to ~/.claude/skills/pikeway/SKILL.md. codex: ~/.codex/skills/pikeway/SKILL.md. opencode: no skill directory, but a tailored MCP hint. Anything else (e.g. cursor) gets the generic hints.

--skill-dirpath

Write SKILL.md into this directory instead (created if missing). Takes precedence over --client.

--no-skillboolean

Don't write the skill file and don't print the skill hint.

Examples

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

Output

All good

✓ 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

Outdated CLI, no key yet, no client given

! 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)

If the saved key is rejected, the second line reads ! saved key is invalid: create one at …. For --client codex the MCP line is codex mcp add pikeway --url https://gw.pikeway.ai/mcp/agent; for opencode it explains the opencode.json entry and 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 version and the gateway it talks to.

skillstring | null

Version in the gateway's SKILL.md; null when it couldn't be fetched.

upToDate · updateboolean · string

update (the install command) is present only when upToDate is false.

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

account (email, wallet address or user id) is present only when key is ok.

skillPath | skillHintstring

Where the skill was written, or a hint when it wasn't. Neither appears with --no-skill.

mcpstring

MCP command or URL for the chosen client.

Errors and exit codes

A missing or invalid saved key is reported, not treated as an error: setup still exits 0. Only a bad --key fails:

Exit	Message	When
2	that does not look like a Pikeway key (pk-…)	The `--key` value doesn't match the key format. Nothing is saved.
3	key rejected: invalid or revoked API key	The gateway refused the `--key` value. Nothing is saved.
1	cannot reach <gateway>: ECONNREFUSED	The gateway could not be reached (DNS, network, wrong PIKEWAY_API_BASE_URL). The code after the colon comes from Node.

Re-run pikeway setup after upgrading the CLI so the skill file matches the new version. See Skill quickstart.

Also accepts the global flags -j, --json. See Global flags and Exit codes.