@verbrail/cli

The VerbRail CLI is the code-first provider onboarding client. Software providers use it to validate bounded discovery sources and inert integration bundles locally, then submit those same reviewed artifacts through VerbRail's governed management API.

The CLI cannot verify, ratify, run conformance, promote, activate, or enable an integration. A proof-specific token can invoke only the fixed governed sandbox exercise and submit its closed, restored receipt.

Requirements

• Node.js 22 or newer
• No VerbRail account or credential for local validation
• A short-lived access token with verbrail:provider:manage only for import or submission commands
• A separately trusted proof-workload token for governed sandbox proof commands

Run without installing

npx --yes @verbrail/[email protected] --help

Local validation

npx --yes @verbrail/[email protected] provider validate source \
  --file verbrail/openapi.yaml \
  --type openapi \
  --application-id app-acme-operations

npx --yes @verbrail/[email protected] provider validate bundle \
  --file verbrail/bundle.json

npx --yes @verbrail/[email protected] provider validate proof \
  --file verbrail/sandbox-proof-receipt.json

Validation is credential-free and safe for pull-request checks. Results are structured JSON; exit code 0 means success and exit code 2 means the local input was rejected.

Governed import and submission

Authenticated commands read a short-lived token only from VERBRAIL_ACCESS_TOKEN. The token cannot be supplied through a command-line flag or bundle file.

export VERBRAIL_API_URL="https://verbrail-control-plane-production.up.railway.app/v1/"
export VERBRAIL_ACCESS_TOKEN="$(your-identity-broker)"

npx --yes @verbrail/[email protected] provider import \
  --file verbrail/openapi.yaml \
  --type openapi \
  --application-id app-acme-operations \
  --registration-mode existing \
  --origin repository:acme/operations-api \
  --idempotency-key provider-import-20260802-001

npx --yes @verbrail/[email protected] provider submit \
  --file verbrail/bundle.json \
  --idempotency-key provider-submission-20260802-001

Authenticated control-plane rejection returns exit code 3. Raw discovery input is sent only by the bounded import command and is never echoed by the CLI.

Governed sandbox proof

The provider-owned harness prepares and restores its fixture. During its exercise phase it invokes the fixed VerbRail graph with the harness run UUID:

npx --yes @verbrail/[email protected] provider proof exercise \
  --run-id 22222222-2222-4222-8222-222222222222 \
  --adapter-id provine.material-shortage-supplier-fixture \
  --adapter-version 1.0.0

npx --yes @verbrail/[email protected] provider proof submit \
  --file verbrail/sandbox-proof-receipt.json \
  --idempotency-key sandbox-proof-22222222-2222-4222-8222-222222222222

The exercise command accepts no message, capability, connector, URL, or arguments. Receipt submission succeeds only when the control plane reconstructs the exact service identity, sandbox scope, three-stage audit trail, and one usage event recorded under the receipt run UUID.

See the complete provider workflow and trust boundaries in the VerbRail provider CLI documentation.