CLI Overview

The NextPay CLI is an agent-first command-line tool for managing your NextPay account. It defaults to JSON output on stdout with errors on stderr, making it easy for AI agents and scripts to parse. When connected to a TTY, it auto-detects and switches to human-friendly output.

Global flags

These flags are available on every command:

Output format

All commands output JSON to stdout by default:

nextpay --env dev workspace list
# {"workspaces": [{"id": "ws_abc123", "name": "Finance", ...}]}

Errors are written to stderr with a non-zero exit code:

nextpay --env dev workspace get ws_invalid 2>/dev/null
# Exit code: 1

Exit codes

The capabilities command

The capabilities command outputs a JSON document describing all available commands, their arguments, valid values, and descriptions. This is designed for AI agents to discover CLI capabilities at runtime:

nextpay capabilities

{
  "commands": [
    {
      "name": "auth login",
      "description": "Log in to your NextPay account via browser",
      "args": []
    },
    {
      "name": "directory list",
      "description": "List directory entries with optional filtering",
      "args": [
        {"name": "--type", "values": ["person", "organization"], "required": false},
        {"name": "--status", "values": ["active", "inactive"], "required": false},
        {"name": "--limit", "default": "25", "required": false}
      ]
    }
  ]
}

Recommended agent workflow:

1. Call nextpay capabilities once at startup to discover commands.
2. Parse the JSON to understand available operations and their parameters.
3. Construct and execute commands as needed.
4. Parse JSON output from each command to make decisions.