@progyai/cli

Customer-side CLI for progy — the permissionless AI proxy. Works against any progy deployment without cloning the server.

First-time setup (2 commands)

npx @progyai/cli init                       # mint a key, save to ~/.progy/credentials
npx @progyai/cli topup --amount 10          # fund it

That's it. progy balance, progy usage, and provider requests through the proxy now Just Work because the saved key is picked up automatically.

Install

Use ad-hoc with npx (recommended — always picks up the latest):

npx @progyai/cli <command>

Or install globally if you use it often:

npm i -g @progyai/cli
progy <command>

The x402 rail pulls in on-chain signing libraries (viem for EVM, @solana/kit for Solana) via the @x402/* packages, so the install footprint is larger than a typical CLI. This is required to sign payments locally without ever sending your key to the server.

Configuration

The CLI resolves the URL and API key from (most-explicit wins):

1. CLI flags (--url, --key)
2. Env vars (PROGY_URL, PROGY_API_KEY)
3. ~/.progy/credentials for the active profile (written by progy init)
4. Default URL https://x.progy.ai (key has no default)

The credentials file is JSON with one entry per profile ({ default: {...}, staging: {...}, ... }), POSIX perms 0600 on the file and 0700 on the directory. Safe to delete at any time — progy init will recreate it.

| Env | Flag | What | |---|---|---| | PROGY_URL | --url | the progy instance to talk to (default https://x.progy.ai) | | PROGY_API_KEY | --key | your progy_sk_… customer key | | PROGY_PROFILE | --profile | credentials profile to use (default default) | | PROGY_TOPUP_PM_ID | --pm | (topup) Stripe PaymentMethod id, e.g. pm_card_visa in test mode | | PROGY_EVM_PRIVATE_KEY | — | (topup x402) EVM wallet private key (0x…) that signs the on-chain payment | | PROGY_SVM_PRIVATE_KEY | — | (topup x402) Solana wallet secret key (base58) that signs the on-chain payment | | PROGY_SVM_RPC_URL | — | (topup x402) optional Solana RPC URL (defaults to a public RPC per network) |

Multi-environment usage

The --profile flag (or PROGY_PROFILE env) lets a single user juggle several progy deployments — e.g. local + staging + prod — without re-running init each time:

progy init --profile prod --url https://progy.example.com
progy init --profile staging --url https://staging.progy.example.com

progy balance --profile prod
PROGY_PROFILE=staging progy whoami

Profile names must be lowercase ASCII with optional dashes (e.g. prod-eu-west-1). The default profile is what's used when no profile is specified.

Commands

Setup

progy init (alias: progy keygen)

Mint a fresh progy API key and save it to ~/.progy/credentials. The new key has zero balance — top it up before making provider requests.

Idempotent: if a key is already configured (env or file), prints what's there and exits 0. Pass --force to mint a new one anyway (which replaces the saved one).

npx @progyai/cli init                       # local default
npx @progyai/cli init --url https://progy.example.com
npx @progyai/cli init --force               # mint a new key over the saved one

progy whoami

Show which account the CLI is configured to use and where the credentials came from (flag, env, or file). Best-effort pings /v1/balance for account_id and balance; falls back to local-only output if the proxy is unreachable.

npx @progyai/cli whoami

progy logout

Delete saved credentials. With no flags, removes the default profile (and the whole file if no other profiles remain); with --profile <name>, removes just that one profile and leaves siblings intact. Exit 0 whether or not the profile existed (safe in cleanup scripts). The server-side account is untouched — only the local copy of the key is removed.

npx @progyai/cli logout
npx @progyai/cli logout --profile staging        # remove just that one profile

progy config

View or update the saved credentials for a profile. Unlike init --force (which mints a brand-new key), this merges — so you can repoint the URL while keeping your existing key, or swap the key while keeping the URL.

npx @progyai/cli config                          # show saved url + key prefix
npx @progyai/cli config --url https://x.progy.ai # repoint the saved profile (keeps the key)
npx @progyai/cli config --key progy_sk_…         # replace the saved key (keeps the url)

Account

progy topup --amount <usd>

Credit your balance via either rail. --rail is auto-picked from what the server advertises (and whether you supplied a Stripe PM); pass it explicitly to force one.

Stripe (card) — requires a Stripe PaymentMethod id:

PROGY_TOPUP_PM_ID=pm_… \
npx @progyai/cli topup --amount 10 --rail stripe

x402 (on-chain USDC) — signs the payment locally with your wallet and settles via the proxy's facilitator. Works on EVM chains (Base, Polygon, …) and Solana. Pick the chain with --network:

# EVM (Base) — needs an EVM private key
PROGY_EVM_PRIVATE_KEY=0x… \
npx @progyai/cli topup --amount 10 --rail x402 --network base

# Solana — needs a base58 secret key (and optionally a dedicated RPC)
PROGY_SVM_PRIVATE_KEY=… \
PROGY_SVM_RPC_URL=https://… \
npx @progyai/cli topup --amount 10 --rail x402 --network solana

If the wallet key env var isn't set, the CLI prompts for it securely (hidden input) — nothing is written to disk. The key signs an EIP-3009 authorization (EVM) or an SPL-USDC transfer (Solana); the proxy never sees your private key. Built on the x402 v2 protocol (PAYMENT-SIGNATURE header) via the @x402/* packages.

progy balance

Show your current balance and the last 20 ledger entries.

progy usage [--since <Nd|Nh|Nm>]

Show your last 50 per-request usage records, optionally filtered to a recent window (e.g. --since 7d, --since 3h).

progy --help / progy <command> --help

Print the dispatch help, or per-command help.

Versioning

This CLI is decoupled from the progy server — it talks to whatever progy instance PROGY_URL points at, over the documented HTTP contract.