CLI overview

Install

The CLI is not on the npm registry yet; install it from this site:

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

Or let your agent do it: tell it set up https://<your-pikeway-site>/SKILL.md. It installs the CLI, saves the skill and checks your key with pikeway setup.

Quick start

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 and inspect are free and work without a key. Everything that spends money or reads your account needs one.

Configuration

API key resolution

Each command that needs a key picks the first one it finds:

• --key pk-… / -k pk-… on the command line
• the PIKEWAY_API_KEY environment variable
• the active key saved with pikeway keys add / activate

Config file

Saved keys live in $XDG_CONFIG_HOME/pikeway/config.json (default ~/.config/pikeway/config.json). The directory is created with mode 700 and the file is written with mode 600. Keys are stored in plain text, so treat the file like a password.

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

Environment variables

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

Global flags

Flag syntax

• Values can be written as --flag value or --flag=value. Short aliases take the next argument: -l 3.
• Short aliases are single letters and cannot be combined: write -j -l 3, not -jl 3.
• Boolean flags (--json, --async, --wait, --no-skill) never take the next argument; --async=false turns one off.
• Unknown flags are not rejected. A misspelled value flag such as --limt 3 is ignored and swallows the next argument, so double-check spelling in scripts.
• Everything after -- is treated as positional words.

JSON output

With -j / --json every command prints exactly the API response body, pretty-printed, on stdout. The extra hint lines (next:, more:, status lines on stderr) are not printed. keys commands, which never contact the gateway, print a small object describing the local change.

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'

Errors are printed to stdout as one line of JSON, with the same exit code as in text mode. details is the gateway's error body when there is one, otherwise null:

{"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"]}}

In text mode, errors go to stderr as error: <message>.

Exit codes

A 402 (insufficient balance or key spend limit) exits with 1 and the message ends with — top up your balance, or pay per call with --x402. See Errors for the gateway messages.

Commands