@enruta/cli

enruta from the terminal: sign in with a developer key, read payment requests, mandates and records, request and inspect reversals, pull dispute packets and representment PDFs, read settlements and reconciliation, manage consents and agent pauses, export a month of records and verify them offline, validate a merchant's UCP endpoint, attest an agent's identity (a CI job's workload identity, an agent key), check a merchant, read the money split of a payment, and manage connected accounts, storefronts and recurrences.

npm i -g @enruta/cli

enruta login                                   # paste a developer key; stored in the macOS keychain
enruta sandbox keys                            # or: a sandbox organization with an agent key and a developer key, no login
enruta requests get preq_…                     # one payment request with its decision, risk, settlement and reversals
enruta mandates list --agent agt_…             # mandates and their state
enruta records list --kind reversal            # records of one kind (payment, reversal, settlement_record, …)
enruta records get rec_… --with-bundle         # a record and its bundle
enruta records export --from 2026-11-01 --to 2026-11-30 --out ./export-2026-11 --kind all
enruta verify ./export-2026-11                 # same as enruta-verify; prints kind and chain for linked records
enruta reversals create --record rec_… --kind refund --amount 9.99 --reason customer_request
enruta reversals list --record rec_…           # reversals and their status, stage, mandate effect
enruta settlements get rec_…                   # stage, amounts, finality class and date
enruta reconciliation lines --period 2026-W38  # the five-leg lines of a week
enruta reconciliation report 2026-W38 --build --sign
enruta disputes packet rec_… --pdf rep.pdf --export stripe
enruta consents list --agent agt_…             # and: enruta consents revoke cns_…
enruta consents revoke cns_… --effective-at 2026-12-01T00:00:00Z --cascade   # later, and stop what is scheduled too
enruta agents pause agt_… --reason "odd retries"   # and: enruta agents resume agt_…
enruta validate https://store.example.com --domain store.example.com
enruta attest workload --agent agt_… --digest $GITHUB_SHA   # inside GitHub Actions (permissions: id-token: write)
enruta attest key --agent agt_… --generate --out agent.jwk.json
enruta merchant verify reamandrule.com         # exit 0 when verified, 1 otherwise
enruta economics preq_…                        # who pays, who receives, who earns; each line with its basis
enruta platform accounts create --kind agents --name "Globex buyer" --external-ref cust_9 --agents Buyer
enruta storefront create --name "Ream & Rule" --slug ream-and-rule --catalog-url https://reamandrule.com/feed.json
enruta recurrence create --agent agt_… --payee tool.example --max 49.00 --cumulative-max 600 --interval monthly --anchor 2026-10-01 --purpose "design tool seat"
enruta recurrence pause rcu_…                  # and: resume, end

Every command accepts --json; --schema prints the JSON Schema (draft 2020-12) of the command's output, so a script can validate what it parses (enruta reversals create --schema, enruta --schema for the index). --api <url> or ENRUTA_API_URL points the CLI at another API base (default https://api.enruta.ai).

Keys

enruta login stores a developer key: on macOS in the login keychain (security add-generic-password -U -a enruta -s enruta-cli), elsewhere in ~/.config/enruta/credentials.json with mode 0600. ENRUTA_API_KEY in the environment overrides the stored key; ENRUTA_CREDENTIALS_STORE=file|keychain forces a store (CI, tests). enruta logout forgets the key. Keys are never written to dotfiles by default and never printed, except by enruta sandbox keys, which exists to hand them out: it asks POST /v0/sandbox/keys (no key needed, rate-limited per IP) for a sandbox organization, an agent key, a developer key and a claim link a person opens to take the organization over.

Reversals

enruta reversals create --record <rec_…> --kind <void|cancel|refund|return|credit|price_adjustment|chargeback_credit> --reason <customer_request|not_as_described|not_received|duplicate|amount_mismatch|policy_violation|merchant_cancel|fraud_suspected|other> [--amount 9.99 --currency USD] [--refund-to original_form_of_payment|credit] asks for a reversal against a payment record. The reply is a decision: allow executes it by stage, step_up prints the approval link, deny prints the reason. Exit code 0 in every case (a denied reversal is a result, not an error); do not retry a denied reversal with another amount. reversals list filters with --record, --kind, --state (requested, pending, completed, failed, denied), --from, --to.

Disputes

enruta disputes packet <rec_…> prints the packet summary (state, CE3.0 elements present and missing, available exports). --pdf <out.pdf> writes the representment PDF; --export stripe|shopify|chargeflow|justt|mastercard prints that export alone (text for Stripe and Shopify, JSON for the others) so it can be piped; --regenerate rebuilds the packet first. disputes list filters with --state, --from, --to, --record.

Reconciliation and settlements

enruta reconciliation lines [--period 2026-W38] [--state matched|partial|unmatched_agent|unmatched_rail|unmatched_merchant] lists the lines; enruta reconciliation report <period> prints the weekly report, --build (re)builds the draft first and --sign signs it with the organization's link key (passkey signing is done in the console), which seals every line and the report as linked records. enruta settlements get <rec_…> prints the settlement record of a payment: rail, stage, amounts, finality class and date, rail references, fulfillment.

Exports and verification

records export creates the export, waits until it is ready, downloads the zip and unpacks it into --out (records, bundles, checkpoints, the bundled verifier enruta-verify.mjs, the schema and a README), then prints the verifier command. --kind reversal,settlement_record (or --kind all) adds the linked records under linked/ and the sealed consents under consents/.

enruta verify runs the same checks as enruta-verify with the same output: canonical form, seal, chain, attestations, keys, strength. For a linked record the header line names its kind and chain (# rec_… org_halvern #12 reversal reversal_of rec_…), an export summary counts records per kind, and --json carries kind and chain. Exit 0 on PASS, 1 on FAIL, 2 when it cannot verify.

Attest an agent's identity

enruta attest workload [--agent <agt_…>] [--digest <sha256:hex | git commit>] [--source <https url>] binds the identity of the CI job that runs the agent to the agent. Inside GitHub Actions (the job needs permissions: id-token: write) it asks the runner's token endpoint (ACTIONS_ID_TOKEN_REQUEST_URL with ACTIONS_ID_TOKEN_REQUEST_TOKEN) for an OIDC token with the audience https://api.enruta.ai and submits it as a workload_identity anchor; --digest also submits a code_digest anchor bound by the same token (the source defaults to the commit URL). Another CI can pass its token in ENRUTA_WORKLOAD_TOKEN. The token is never printed, in either output mode. The reply shows the attestations and the agent's assurance level after; the command exits 1 when Enruta did not verify an anchor, with the reason on stderr, so a CI step fails visibly.

permissions:
  id-token: write
steps:
  - run: npx @enruta/cli attest workload --agent agt_procurement_02 --digest ${{ github.sha }}
    env:
      ENRUTA_API_KEY: ${{ secrets.ENRUTA_DEVELOPER_KEY }}

enruta attest key [--agent <agt_…>] (--jwk <private.jwk.json> | --generate [--out <file>]) proves the agent holds a key: it asks POST /v0/attestations/nonce, signs { agent_id, nonce, iat } as a compact JWS (ES256 for a P-256 key, EdDSA for Ed25519) and submits the public JWK with the proof. --generate writes a new P-256 key with mode 0600 (it refuses to overwrite a file); the private key never leaves the machine and is never printed.

With an agent key, --agent can be left out (the agent is read from GET /v0/me).

Merchants and the money split

enruta merchant verify <domain> prints the merchant check (domain, UCP keys, checkout signature, seller organization, conformance) and exits 0 when the merchant is verified, 1 when it is unverified or a mismatch. enruta economics <preq_…> prints who pays, who receives and who earns on one payment, each party's basis (actual, estimate, plan), the flows, and the source and date of every estimate.

Platforms, storefronts, recurrences

enruta platform accounts ls [--kind agents|sellers] [--state active|suspended] and enruta platform accounts create --kind agents|sellers --name <name> [--external-ref <ref>] [--owner-email <email>] [--domains <d1,d2>] [--agents <n1,n2>] manage a platform's connected accounts (keys for an account are created through the API and shown once). enruta storefront ls and enruta storefront create --name <name> --slug <slug> (--catalog-url <https url> | --catalog <file.json>) [--currency] [--custom-domain] [--psp-connection psc_…] manage hosted storefronts. enruta recurrence ls [--agent] [--state active|paused|ended], enruta recurrence create --agent --payee --max --cumulative-max --interval weekly|monthly --anchor <date> --purpose [--currency] [--variable <pct>] [--end-date] [--consent cns_…] and enruta recurrence pause|resume|end <rcu_…> manage standing payments; every occurrence is decided against the policy like any payment.

Validate a merchant

enruta validate <endpoint> [--domain <domain>] [--platform-profile <url>] [--profile <url>] [--product <id>] [--timeout <seconds>] runs the UCP conformance vectors of @enruta/sdk against a merchant's REST endpoint and prints one line per vector:

# enruta validate https://store.example.com  (store.example.com)  UCP 2026-08-25
result  vector                           detail
ok      discovery.profile                ucp.version 2026-08-25, Ream & Rule
ok      lifecycle.complete               200 completed, order ord_… via mock_payment_handler
skip    mandate.required                 skipped: no platformProfileUrl given
ok      signature.merchant_authorization detached ES256 JWS verifies with key key_…
# PASS: 17 of 17 passed, 2 skipped in 412 ms

Exit 0 when every applicable vector passes, 1 otherwise, 2 on a usage error. --platform-profile https://app.enruta.ai/.well-known/agent-profile.json enables the two AP2 vectors (the merchant must be able to fetch that profile). The runner completes one checkout with the UCP mock payment handler (success_token, no money moves) and cancels the other sessions it opened; it presents a data: platform profile without AP2, and --profile <https url> replaces it for merchants that only accept https profiles. The platform's POST /v0/sellers/conformance runs the same suite and issues the badge.

npm run build bundles the CLI into dist/enruta.mjs, one file that needs only Node 20+.

Apache-2.0.