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 Harbor 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
}

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

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 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:

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

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

Subcommands accept Gateway-aligned flags for amounts, rails, and idempotency keys. --request-id is forwarded as a correlation header.

paybond guardrails

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

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

JSON data fields (list): exports[] with job_id, status, created_at, expires_at, scope.

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

Related

• Authentication & tenant binding
• Error handling
• MCP server
• Coding-agent setup
• API error envelope