Overview
CLI reference
Generate, import and validate config; run and diagnose the gateway; reconcile payments and back up its database.
The package includes agent-commerce to generate, import and validate config, run and diagnose the gateway, and back up its database. Validation uses the gateway's config loader.
npx @devlab.group/agent-commerce --helpCommands
| Command | What it does |
|---|---|
init | interactively generate config.yaml |
import openapi <source> | convert an OpenAPI 3.x document into resource drafts |
validate | validate config.yaml; exit non-zero if invalid |
start | run the gateway config.yaml describes |
doctor | diagnose config, gateway, backend, protocol and payment health |
reconcile | resolve uncertain payment attempts from chain evidence |
resolve <attemptId> | record an operator verdict on one unresolved payment attempt |
backup --out <dir> | back up the receipt database and unimported legacy files |
demo | run the documented quickstart, checking each step |
version | print the CLI version and pinned protocol/SDK versions |
Global options
-v, --version-h, --helpConfig resolution
Commands that read configuration take --config <path>. Without it they use AGENT_COMMERCE_CONFIG, then config.yaml in the working directory. When .deploy/local.json exists (written by npm run chain:deploy), validate and doctor fill the local X402_* and MERCHANT_WALLET placeholders from it and say so.
validate, start, doctor, reconcile, resolve and backup also take --env-file <path>, which fills ${VAR} placeholders from a file such as .env. A variable already set in the environment wins over the file.
Exit codes
| Code | Meaning |
|---|---|
0 | success — warnings included, unless a command's --strict says otherwise |
1 | failure: invalid config, a FAIL check, a failed import, demo step or gateway start, a reconcile run that did not complete, a refused resolution, an incomplete backup, a refused overwrite, an aborted init, or an unknown command or option |
9 | Node rejected an unreadable --env-file path for any command that takes one before the CLI ran (observed on Node 24.8.0) |
Status lines start with PASS, WARN, FAIL or INFO, so logs stay greppable in CI. Reports, step markers such as demo's ==> and OK, and notes such as validate's local chain manifest line print without one. Resolved secrets are never printed — errors name the variable, not its value.