CLI contract

This document is the canonical contract for the paybond CLI shipped by both kits:

• TypeScript: @paybond/kit exposes the paybond binary.
• Python: paybond-kit exposes the paybond binary.

Both implementations must expose the same command names, global flags, JSON output keys, exit codes, error categories, and redaction behavior. Parity tests compare --help, JSON schemas, and error handling across both kits.

Legacy entry points remain as thin wrappers over this tree:

Design rules

• Tenant scope always comes from authenticated credentials (PAYBOND_API_KEY or the configured env file). Normal tenant-scoped commands must not accept tenant IDs from unauthenticated CLI arguments.
• Human output defaults to safe, masked values suitable for terminals and CI logs.
• Machine output uses --format json and returns stable, documented keys. JSON mode never omits required envelope fields.
• Destructive or live-money actions require --yes and are still subject to server-side RBAC.
• Secrets on disk use file mode 0600. Default .env.local targets are added to .gitignore when needed. Custom env-file paths inside a git repo must already be ignored.

Global flags

These flags are accepted on every subcommand unless a command explicitly documents an exception. Global flags may appear before or after the subcommand.

Commands may define additional flags. Command-specific flags must not redefine global flag names with different semantics.

Output formats

Table (default)

• Write human-readable lines to stdout.
• Write errors to stderr.
• Apply redaction rules to every field before printing.
• Do not print raw API keys, capability tokens, signing seeds, or API bearer tokens.
• Success lines should be concise and actionable (for example, masked key identity, resource IDs, and next steps).

JSON (--format json)

Every JSON response uses one envelope regardless of command:

{
  "ok": true,
  "command": "whoami",
  "data": {},
  "warnings": [],
  "request_id": "01JABY5EXAMPLE",
  "error": null
}
{
  "ok": true,
  "command": "whoami",
  "data": {},
  "warnings": [],
  "request_id": "01JABY5EXAMPLE",
  "error": null
}

On failure:

{
  "ok": false,
  "command": "keys revoke",
  "data": null,
  "warnings": [],
  "request_id": "01JABY5EXAMPLE",
  "error": {
    "category": "forbidden",
    "code": "cli.rbac.denied",
    "message": "caller lacks keys:revoke permission",
    "details": {
      "gateway_status": 403,
      "gateway_code": "auth.forbidden"
    }
  }
}
{
  "ok": false,
  "command": "keys revoke",
  "data": null,
  "warnings": [],
  "request_id": "01JABY5EXAMPLE",
  "error": {
    "category": "forbidden",
    "code": "cli.rbac.denied",
    "message": "caller lacks keys:revoke permission",
    "details": {
      "gateway_status": 403,
      "gateway_code": "auth.forbidden"
    }
  }
}

Envelope fields:

Error object fields:

JSON mode writes the envelope to stdout only (including failures). Exit code still reflects success or failure.

Exit codes

When Gateway returns a structured error, the CLI maps HTTP status to exit code:

Error categories

Redaction rules

Apply these rules in table output and in any human-readable log lines. JSON data fields follow the per-command schema below; secret fields are omitted or replaced with masked placeholders unless the command explicitly documents a full-value JSON field for automation.

Key masking algorithm (both kits must match):

1. Split the key on _.
2. When the shape is paybond_sk_{environment}_{key_id}_{secret}, emit paybond_sk_{environment}_{key_id[0:8]}...{key_id[-4:]} when len(key_id) > 12, otherwise paybond_sk_{environment}_redacted.
3. Otherwise emit paybond_sk_....

Command tree

Top-level invocation:

paybond [--global-flags] <command> [<subcommand> ...] [args] [--command-flags]
paybond --help
paybond <command> --help
paybond [--global-flags] <command> [<subcommand> ...] [args] [--command-flags]
paybond --help
paybond <command> --help

paybond login

Sandbox device login. Writes PAYBOND_API_KEY to the env file.

Inherits global flags --gateway, --env-file, --no-open, --format.

Table output (success): verification URL, user code, env file path, masked key, target tenant, optional expiry notice.

login is the one command that intentionally performs a local secret write; it still never prints the raw key.

JSON data fields:

These next four commands are post-login operator surfaces. They do not replace login, init, doctor, or dev loop for first success — use them after credentials exist to inspect state, script sticky context, or deep-link into Console for rare admin tasks.

paybond status

Summarize sandbox auth, the local policy file, last smoke/trace event, and the local trace dashboard URL. Tenant scope comes from authenticated credentials only — never from CLI tenant flags. Useful offline even when principal lookup fails (auth still reports key presence / next steps).

Inherits global --format, --gateway, --env-file, --profile.

JSON data fields:

Examples: paybond status, paybond status --format json. Suggested next: paybond control --once --format json.

paybond shell

Interactive REPL with sticky --gateway / --env-file / --profile context (Heroku-style). Nested shell or control inside the REPL is refused. Non-TTY, CI, and --format json must not hang — use --exec for one-shot.

JSON data fields:

Examples: paybond shell, paybond shell --exec "status", paybond shell --exec "whoami --format json".

paybond control

Live read-mostly control-plane TUI over gateway intents, agent receipts, local policy, spend decisions, and denials. TypeScript uses Ink; Python uses a terminal panel loop. Honors NO_COLOR and TTY detection. Tenant scope comes from authenticated credentials only.

JSON / snapshot data fields: mode (snapshot | tui), active_panel, tenant_id, environment, gateway, trace_url, panels (intents, receipts, policy, spend, denials), generated_at, limitations[], and next_commands[] in snapshot mode.

Examples: paybond control, paybond control --once --format json, paybond control --once --limit 5.

paybond open

Explicit deep-link escape hatch to Console (or local trace / docs) for rare admin tasks. Not the default path for day-to-day Kit work — prefer status, control, and shell.

paybond open <resource> [<id>] [--port <n>] [--no-open]
paybond open <resource> [<id>] [--port <n>] [--no-open]

Console origin: PAYBOND_CONSOLE_BASE_URL or PAYBOND_PUBLIC_BASE_URL, else http://127.0.0.1:3000. Docs origin: PAYBOND_DOCS_BASE_URL, else https://paybond.ai/docs.

JSON data fields: resource, url, purpose, opened, note.

Examples: paybond open console, paybond open billing --no-open, paybond open intent <uuid>, paybond open export job-123 --no-open, paybond open trace.

paybond init guardrail

Scaffold a sandbox paid-tool guardrail integration file.

Allowed --framework values: generic, provider-agnostic, openai, claude, anthropic, gemini, google-ai, vercel-ai, langgraph, mcp.

JSON data fields: out, preset, framework, bytes_written.

paybond mcp

mcp install flags:

Generated MCP configs must reference PAYBOND_ENV_FILE by default, not embed raw API keys.

JSON data fields (install): host, scope, config_path, server_command, printed. When printed is true (local scope) and --format json is set, payload contains the generated config text.

paybond doctor

Validate local runtime, package version, env file, key shape, principal lookup, and optional agent/MCP setup.

JSON data fields: checks[] with { name, ok, message, details? }, summary (pass | fail).

With --agent, also runs agent middleware sandbox smoke when sandbox credentials are present.

paybond adyen

Read-only BYO Adyen Checkout settlement readiness against GET /v1/admin/settlement/config. Does not upsert API keys, HMAC secrets, or stored payment methods — use Console Settlement or POST /v1/admin/settlement/adyen/destination.

JSON data fields (ready): ready, checks[], summary, checklist_lines.

JSON data fields (doctor): checks[], summary, checklist_lines, next_steps.

Tenant walkthrough: Configure Adyen settlement. Shopify has a larger orchestration surface documented separately in Shopify CLI workflow.

paybond flutterwave

Read-only BYO Flutterwave Virtual Account settlement readiness against GET /v1/admin/settlement/config. Does not upsert secret keys or webhook secrets — use Console Settlement or POST /v1/admin/settlement/flutterwave/destination.

JSON data fields (ready): ready, checks[], summary, checklist_lines.

JSON data fields (doctor): checks[], summary, checklist_lines, next_steps.

Tenant walkthrough: Configure Flutterwave settlement.

paybond dev

Local sandbox developer workflows: travel smoke with checklist output, trace dashboard, optional WireMock Gateway (dev up), and a guided login → policy → validate → smoke loop.

paybond dev smoke

JSON data fields (smoke): bind, execute, trace_url, audit_log, offline (when set). Timeline events are persisted under .paybond/dev-trace.jsonl.

paybond dev trace

Serves a self-contained HTML dashboard at / and /runs/<run-id>. Polls /api/events for timeline data. Run from the same project directory as dev smoke / dev loop so .paybond/dev-trace.jsonl is found.

JSON data fields (trace): trace_url, port, events[] (each event may include trace_events[] with structured middleware records: tool_selected, spend_authorized, tool_executed, evidence_submitted, spend_finalized, plus steps[] for the vertical timeline UI).

paybond dev loop

JSON data fields (loop): steps[], smoke, trace_url, audit_log, banner_lines[], offline (when set).

paybond dev up

Starts WireMock with bundled Gateway stubs under kit/dev/wiremock/mappings/ (also packaged in the Python wheel). Includes an x402 fund sequence for intent aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa: mappings 11-x402-fund-challenge.json (402 with payment-required), 12-x402-fund-pending.json (202), and 13-x402-fund-success.json (200 with capability_token). Use with paybond --gateway http://127.0.0.1:18089 intents fund ... or fundWithX402 / fund_with_x402 to rehearse the handshake without a remote sandbox API.

JSON data fields (up): gateway_url, port, wiremock_dir, container_name, status, next_commands[].

Dev smoke and loop append audit events to .paybond/dev-audit.jsonl under the working directory.

paybond config

Config is profile-scoped when --profile is set.

paybond whoami

Resolve the authenticated principal and tenant realm.

JSON data fields: tenant_id, tenant_uuid, environment, service_account_role, principal (Gateway principal payload, secrets stripped).

paybond keys

JSON data fields (list): keys[] with key_id, key_masked, role, created_at, expires_at, status.

JSON data fields (create, rotate): key_id, key_masked, plus one-time plaintext api_key when the Gateway returns a newly minted secret.

paybond intents

Read vs mutation paths: list and get call Gateway operator routes directly and do not require agent recognition. Intent mutation subcommands open a Paybond session (withPaybondCli / with_paybond_cli), sign a request-bound recognition proof over the wire body (or {} for fund), and delegate to the SDK Harbor surface.

Shared recognition flags (intent mutations):

create, fund, evidence, and settlement-confirm require these credentials when Gateway Harbor recognition enforcement is enabled.

paybond intents create

paybond intents fund <intent_id>

Harbor receives an empty POST body; the recognition proof binds to {}. On x402 rails, a 402 response includes payment-session metadata in the structured CLI JSON (statusCode, paymentRequired, etc.). Retry with a fresh recognition proof plus --payment-signature.

paybond intents evidence <intent_id>

The recognition proof binds to the exact wire body bytes Harbor verifies (same digest rule as agent harbor evidence smoke, but without Kit-side payee signing).

JSON data fields (evidence): intentId / intent_id, tenant, state, optional predicatePassed / predicate_passed.

paybond intents settlement-confirm <intent_id>

JSON data fields (fund): statusCode (or status_code in Python CLI output), intentId / intent_id, tenant, state, settlementRail / settlement_rail, currency, amountCents / amount_cents, funded, optional capabilityToken / capability_token, optional paymentRequired / payment_required, optional paymentResponse / payment_response, optional funding.

--request-id is forwarded as a correlation header on all subcommands. Responses redact capability_token / capabilityToken and other sensitive fields using the shared CLI redaction rules.

paybond guardrails

JSON data fields (bootstrap): tenant_id, intent_id, capability_token, operation, requested_spend_cents, sandbox_lifecycle_status.

paybond agent

Agent middleware commands wrap PaybondAgentRun and PaybondToolInterceptor. They default to sandbox-only unless --production is passed (live API keys require the explicit flag).

JSON data fields (run bind): run_id, tenant_id, intent_id, capability_token, operation, sandbox_lifecycle_status, allowed_tools[].

JSON data fields (run trace): run_id, intent_id, trace_events[] (tool_selected, spend_authorized, spend_denied, approval_required, tool_executed, evidence_submitted, spend_finalized), steps[], trace_url, trace_file, updated_at. Table mode prints trace_lines[] instead of the default key-value table.

JSON data fields (tool execute): authorization, tool_result, evidence (submitted, intent_state, predicate_passed, sandbox_lifecycle_status).

When evidence.submitted is false and the error category is gateway, check that --result-body matches the preset (for example cost_and_completion requires top-level status and cost_cents). Harbor predicate rejections are often surfaced as HTTP 502 harbor_evidence_failed through the Gateway.

JSON data fields (sandbox smoke): bind, execute (same shapes as above).

Use --format json for automation. --write-env on run bind appends PAYBOND_INTENT_ID, PAYBOND_CAPABILITY_TOKEN, and PAYBOND_RUN_ID to an env file.

paybond spend authorize

Authorize delegated spend for a tool call.

JSON data fields: authorized, intent_id, operation, requested_spend_cents, deny_reason (when not authorized).

paybond signal

Each subcommand accepts resource selectors documented in the SDK references.

paybond receipts

paybond mandates

paybond a2a

paybond audit exports

Delegates to paybond.audit.exports on the Kit SDK (POST /v1/compliance/audit-exports and related routes). Tenant scope comes from authenticated credentials only — never pass a tenant id. Progress lines for create --wait go to stderr; use --format json for the envelope. Operator Console remains available for investigation UI (paybond open compliance-exports).

paybond audit exports create flags: --time-start, --time-end (RFC 3339), --intent-id, --case-id, --operator-did, --includes a,b, --disclosure-tier standard\|extended, --retention-hours <n>, --wait, --output <path>, --timeout-seconds <n>.

JSON data fields (create): job, waited, output, bytes_written, next_commands[].

JSON data fields (list): exports[] with job_id, status, created_at, expires_at. Optional next_cursor when the Gateway paginates results.

SDK: paybond.audit.exports.create|list|get|delete|verify (TypeScript and Python) — same surface as the CLI. MCP readonly: paybond_list_audit_exports, paybond_get_audit_export when --tool-policy readonly (no create via MCP). Bundle verify stays SDK/CLI only.

Security invariants

Both kits must enforce:

1. No live device login — reject --env live and hidden live flags.
2. Git-ignore gate — refuse to write secret files that are not ignored inside a git repository (except when adding the default .env.local to .gitignore).
3. 0600 secret files — env files containing API keys are written with owner-read/write only.
4. No tenant override — reject --tenant-id and similar unauthenticated tenant selectors on normal commands.
5. Confirmation gate — refuse destructive subcommands without --yes.
6. Operator key expectation for login — reject device-login tokens whose role is not operator.

Parity and testing

Both kits must maintain:

• Snapshot parity for paybond --help and each subcommand --help.
• JSON shape parity for whoami, doctor, keys list, guardrails bootstrap, and representative error cases.
• Identical exit codes and error categories for the same failure inputs.
• Identical key masking output for the same raw key material.

Run kit tests from the repository root:

cd kit/ts && npm run test
cd kit/python && uv run pytest
cd kit/ts && npm run test
cd kit/python && uv run pytest

Related

• Authentication & tenant binding
• Error handling
• MCP server
• Coding-agent setup
• Shopify CLI workflow — paybond shopify orchestration surface
• Configure Adyen settlement — paybond adyen ready / doctor
• Configure Flutterwave settlement — paybond flutterwave ready / doctor
• API error envelope