Commands
Every metro command and its output contract.
Every metro command, its mode, whether it touches the API, and its output schemaVersion. Prefer --json when scripting; agents load --markdown.
Source
Generated from metro docs command-reference --markdown in metrocli/metro @146bf3e. Source schemaVersion: metro.docs.command-reference.v1.
- schemaVersion:
metro.docs.command-reference.v1
Commands
| id | command | group | mode | status | apiAccess | schemaVersion | description |
|---|---|---|---|---|---|---|---|
| init | metro init [--agent] [--prod] [--plain] | init | setup | local | read | none | First run: create ~/.metro/.env (mode 600), add the sandbox key (hidden input), check it with one read-only Metronome call, and leave metro read-only. --agent prints the steps for a human instead of prompting; --prod adds only the production key after a y/N confirmation. |
| init.check | metro init --check [--json] | init | inspect | local | read | metro.init.check.v1 | Report each configured key as missing, rejected, or working. Exits 1 while the sandbox key is not working. |
| shape.list | metro shape list [--json] | shape | explain | local | none | metro.shape.list.v1 | List supported reviewed shapes and maturity levels. |
| shape.explain | metro shape explain <shape> [--json] | shape | explain | local | none | metro.shape.explain.v1 | Explain a shape, including required input, maturity, blocked modes, rule IDs, and sources. |
| validate.shape | metro validate --shape <shape> --file <input.json|yaml> [--json] | validate | validate | local | none | metro.validation.v1 | Validate local JSON or YAML input against a supported shape before any API client loads. |
| input.normalize | metro input normalize (--shape <shape>|--api <endpoint-id>) --file <input.json|yaml> [--json] | input | validate | local | none | metro.input.normalize.v1 | Normalize local JSON or YAML workflow shape input or expert API request input into stable canonical JSON with validation status, secret-scan refusal, and deterministic hash output. |
| workspace.explain | metro workspace explain [--sandbox|--prod] [--json] | workspace | explain | local | none | metro.workspace.v1 | Explain the active workspace catalog model, rate-card bindings, API token conventions, and plan intents for optimal shape routing. |
| workspace.status | metro workspace status --file <profiles.json> --profile <name> [--check-env] [--json] | workspace | explain | local | none | metro.workspace.status.v1 | Bind a tenant profile to the workspace model and report whether the Metronome key env var is configured (name only, never the secret). |
| workspace.list | metro workspace list [--json] | workspace | explain | local | none | metro.workspace.list.v1 | List installed workspace packs and show which pack is active from sticky resolution. |
| workspace.current | metro workspace current [--json] | workspace | explain | local | none | metro.workspace.current.v1 | Show the resolved workspace pack and which source won (cli flag, env, session, profile, sticky config, or built-in default). |
| workspace.use | metro workspace use <pack> [--write] [--json] | workspace | explain | local | none | metro.workspace.use.v1 | Set the active workspace pack for this process; with --write, persist defaultWorkspacePack in ~/.metro/config.json so later shells stay sticky. |
| plan.template | metro plan template <intent> (--sandbox|--prod) [--out <out.json>] [--token <name>] [--action-code <code>] [--display-name <text>] [--price <n>] [--file <profiles.json>] [--profile <name>] [--json] | plan | explain | local | none | metro.workspace.input-template.v1 | Emit a focused inputTemplate JSON payload for a workspace intent, optionally writing it to a file for validate/preview follow-on. |
| plan.list | metro plan list [--json] | plan | explain | local | none | metro.workspace.plan.list.v1 | List workspace-aware plan intents that map billing goals to optimal shapes and rejected API paths. |
| plan.intent | metro plan <intent> (--sandbox|--prod) [--token <name>] [--action-code <code>] [--display-name <text>] [--price <n>] [--file <profiles.json>] [--profile <name>] [--json] | plan | preview | local | none | metro.workspace.plan.v1 | Build a workspace-aware plan for a billing intent: optimal shape, catalog mode, rejected paths, commands, verification reads, and input templates. |
| route.goal | metro route --goal "<billing goal>" [--api <endpoint-id>] (--sandbox|--prod) [--json] | route | validate | local | none | metro.workspace.route.v1 | Match a billing goal or API endpoint to the optimal workspace plan intent and refuse suboptimal catalog paths. |
| audit.export.classify | metro audit export classify --file <audit-export.json> [--token <name>] (--sandbox|--prod) [--json] | audit | validate | local | none | metro.workspace.audit-export.v1 | Classify exported Metronome audit log rows by action histogram and map to workspace plan intents (local file only). |
| audit.export.plan | metro audit export plan --token <name> (--sandbox|--prod) [--json] | audit | explain | local | none | metro.workspace.audit-export.v1 | Build the local audit export workflow (security.getAuditLogs read plan steps + classify); does not perform live reads. |
| package.preview.pro-annual-self-serve-v2 | metro package preview --shape pro-annual-self-serve-v2 --file <input.json|yaml> (--sandbox|--prod) [--json] | package | preview | local | none | metro.preview.v1 | Preview annual self-serve package v2 with separable plan fee and monthly-drip or lump-sum recurring_commits. |
| package.preview.free-credit-trial | metro package preview --shape free-credit-trial --file <input.json|yaml> (--sandbox|--prod) [--json] | package | preview | local | none | metro.preview.v1 | Validate and preview a free-trial package with recurring credit grants, auto-expiry (duration in days), and no Stripe. Enforces commit_duration.unit PERIODS, duration.value as a string, starting_at_offset, and proration - do not hand-craft this payload. |
| package.preview.pro-annual | metro package preview --shape pro-annual --file <input.json|yaml> (--sandbox|--prod) [--json] | package | preview | local | none | metro.preview.v1 | Build a local package preview payload plan, side-effect summary, verification plan, and canonical hash. |
| package.archive.preview.alias-handoff | metro package archive preview --file <input.json|yaml> (--sandbox|--prod) [--shape package-alias-archive-handoff] [--json] | package | preview | local | none | metro.preview.v1 | Build a local package archive plan that refuses old-version archive until the replacement alias is live and verified, without calling Metronome. |
| credit.preview.complimentary-credit-grant | metro credit preview --shape complimentary-credit-grant --file <input.json|yaml> (--sandbox|--prod) [--json] | credit | preview | local | none | metro.preview.v1 | Build a local complimentary-credit preview payload plan, side-effect summary, verification plan, and canonical hash. |
| credit.preview.paid-credit-top-up | metro credit preview --shape paid-credit-top-up --file <input.json|yaml> (--sandbox|--prod) [--json] | credit | preview | local | none | metro.preview.v1 | Build a local paid credit top-up preview payload plan with fiat invoice schedule, Stripe payment gate, side-effect summary, and read-back plan. |
| billing-provider.preview.stripe-attachment | metro billing-provider preview --shape stripe-billing-provider-attachment --file <input.json|yaml> (--sandbox|--prod) [--json] | billing-provider | preview | local | none | metro.preview.v1 | Build a local Stripe billing-provider attachment payload plan, Stripe draft-behavior plan, verification plan, and canonical hash. |
| customer.setup.preview | metro customer setup preview --file <input.json|yaml> (--sandbox|--prod) [--shape customer-setup] [--json] | customer | preview | local | none | metro.preview.v1 | Build a local customer setup plan with identity, ingest alias collision checks, optional Stripe billing-provider config, hierarchy posture, custom-field approval evidence, read-back checks, and a canonical hash. |
| contract.move-plan.preview.no-immediate-invoice | metro contract move-plan preview --file <input.json|yaml> (--sandbox|--prod) [--shape package-plan-move-no-immediate-invoice] [--json] | contract | preview | local | none | metro.preview.v1 | Build a local package plan-move preview using updateEndDate plus a RENEWAL successor contract, without calling Metronome. |
| contract.move-plan.preflight | metro contract move-plan preflight --to=<alias> (--customer-id=|--external-id=|--ingest-alias=|--name=) [--from=<alias>] (--sandbox|--prod) [--cutover=ISO|--cutover-mode=renewal-boundary|current-hour|next-hour] [--out=move.json] [--json] | contract | preflight | live | read | metro.contract-move-plan.preflight.v1 | Live-read customer contracts, invoices, and package aliases; infer renewal-boundary cutover; write move.json plus preview hash for apply. |
| customer.resolve | metro customer resolve (--customer-id=|--external-id=|--ingest-alias=|--name=) (--sandbox|--prod) [--json] | customer | read | live | read | metro.customer.resolve.v1 | Resolve a Metronome customer by UUID, external/custom id, ingest alias, or company name (live list/search). |
| customer.balances | metro customer balances (--customer-id=|--external-id=|--ingest-alias=|--name=) (--sandbox|--prod) [--contract-id=] [--min-balance=<n>] [--only-active] [--only-nonzero] [--out=<file.json>] [--json] | customer | read | live | read | metro.customer-balances.v1 | Live-read every commit/credit balance for a customer (contracts/list + customerBalances/list), tagging each row with contract_active and ledger_adjustable. |
| tenant.snapshot | metro tenant snapshot show|refresh|diff [--sandbox|--prod] [--against=prev|production|<file>] [--json|--markdown] [--dir <path>] | tenant | explain | local | none | metro.tenant.snapshot.show.v1 | Show, re-classify, or diff the local tenant snapshot under ~/.metro/snapshots (pattern + bound catalog). Live refresh of inventory is metro catalog bind --write. |
| catalog.bind | metro catalog bind (--sandbox|--prod) [--write] [--file <profiles.json>] [--profile <name>] [--json] | catalog | read | live | read | metro.catalog.bind.v1 | Discover rate cards, products, billable metrics, and credit types; write workspaceCatalog into profiles.json for generic pack plans. |
| contract.move-plan.apply | metro contract move-plan apply --file <move.json> (--sandbox|--prod) --confirm-hash <hash> [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] | contract | apply | pack-op | write | metro.contract-move-plan.apply.v1 | Dry-run validates move.json offline; live --apply runs updateEndDate + RENEWAL successor with post-apply read-back. Production requires ALLOW_DANGEROUS_SCRIPT or --confirm-prod-apply. |
| contract.move-plan.bulk-preflight | metro contract move-plan bulk-preflight --to=<alias> --roster-file=<path> (--sandbox|--prod) [--cutover=ISO|--cutover-mode=…] [--out-dir=<dir>] [--out=manifest.json] [--delay-ms=300] [--json] | contract | preflight | live | read | metro.contract-move-plan.bulk-preflight.v1 | Runs contract move-plan preflight per customer in a roster file (one customer id per line), flags predecessor balance carrying into RENEWAL successors, and writes a bulk manifest with per-customer confirm hashes. |
| contract.move-plan.bulk-apply | metro contract move-plan bulk-apply --file <manifest.json> (--sandbox|--prod) [--apply] [--limit=N] [--delay-ms=300] [--confirm-prod-apply=<token>] [--json] | contract | apply | pack-op | write | metro.contract-move-plan.bulk-apply.v1 | Replays contract move-plan apply for every preflight-ok entry in a bulk manifest, continuing on per-customer failure. Use --limit=N to canary before the full roster; each entry still requires its own preflight confirm hash. |
| contract.extend-trial.preflight | metro contract extend-trial preflight --extend-to=<ISO>|--extend-by-days=<N> (--customer-id=|--external-id=|--ingest-alias=|--name=) [--contract-id=] (--sandbox|--prod) [--out=extend.json] [--json] | contract | preflight | live | read | metro.contract-extend-trial.preflight.v1 | Live-read the active contract, compute an hour-boundary extension of its current ending_before, and write an updateEndDate payload plus confirm hash for apply. Refuses truncations and open-ended contracts. |
| contract.extend-trial.apply | metro contract extend-trial apply --file <extend.json> (--sandbox|--prod) --confirm-hash <hash> [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] | contract | apply | pack-op | write | metro.contract-extend-trial.apply.v1 | Dry-run validates the extend.json payload offline; live --apply runs a single updateEndDate call with post-apply read-back. Production requires ALLOW_DANGEROUS_SCRIPT or --confirm-prod-apply. |
| contract.expire.preflight | metro contract expire preflight (--customer-id=|--external-id=|--ingest-alias=|--name=) [--contract-id=] [--cutover-mode=current-hour|next-hour|--ending-before=<ISO>] (--sandbox|--prod) [--out=expire.json] [--json] | contract | preflight | live | read | metro.contract-expire.preflight.v1 | Live-read the active contract and write an updateEndDate truncation payload (default cutover: current UTC hour). Prefer --customer-id for a 1-call resolve. |
| contract.expire.apply | metro contract expire apply --file <expire.json> (--sandbox|--prod) --confirm-hash <hash> [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] | contract | apply | pack-op | write | metro.contract-expire.apply.v1 | Dry-run validates expire.json offline; live --apply runs updateEndDate with post-apply read-back proving ending_before. |
| ledger-adjustment.preflight | metro ledger-adjustment preflight (--amount=<signed-int>|--archive-balance-id=<balance-id>) --reason="<reason>" (--customer-id=|--external-id=|--ingest-alias=|--name=) [--contract-id=] [--balance-id=] (--sandbox|--prod) [--out=ledger.json] [--json] | ledger-adjustment | preflight | live | read | metro.ledger-adjustment.preflight.v1 | Live-read customer balances, resolve exactly one target commit balance (by contract/balance filter or unambiguous match), and write a confirm-hashed payload for apply. --amount does a partial addManualBalanceLedgerEntry adjustment. --archive-balance-id fully archives one grant via contracts.edit archive_credits/archive_commits (all-or-nothing, no amount) - the two are mutually exclusive. Refuses ambiguous targets and removals larger than the available balance. |
| ledger-adjustment.apply | metro ledger-adjustment apply --file <ledger.json> (--sandbox|--prod) --confirm-hash <hash> [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] | ledger-adjustment | apply | pack-op | write | metro.ledger-adjustment.apply.v1 | Dry-run validates the ledger.json payload offline; live --apply detects the payload shape and runs either addManualBalanceLedgerEntry (partial amount) or contracts.edit archive_credits/archive_commits (full grant archive), with post-apply balance read-back. Production requires ALLOW_DANGEROUS_SCRIPT or --confirm-prod-apply. Highest-risk write - requires owner-approved business reason. |
| contract.repair-accidental.preflight | metro contract repair-accidental preflight --archive-contract-id=<id> --keep-contract-id=<id> --reason="<why accidental>" (--customer-id=|--external-id=|--ingest-alias=|--name=) [--restore-ending-before=<ISO>] (--sandbox|--prod) [--out=repair.json] [--json] | contract | preflight | live | read | metro.contract-repair-accidental.preflight.v1 | Live-read both named contracts plus recent customer invoices, refuse if the contract to archive has any FINALIZED or Stripe-synced invoice (danger-zone SKILL.md §1.1/§7 - void_invoices never refunds Stripe), and write a contracts.archive(void_invoices:true) [+ optional updateEndDate restore] payload with a confirm hash. Which contract is "accidental" is always an explicit human-supplied id, never inferred. |
| contract.repair-accidental.apply | metro contract repair-accidental apply --file <repair.json> (--sandbox|--prod) --confirm-hash <hash> [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] | contract | apply | pack-op | write | metro.contract-repair-accidental.apply.v1 | Dry-run validates the repair.json payload offline; live --apply archives the accidental contract with void_invoices:true, optionally restores the kept contract's ending_before, then reads both back. Production requires ALLOW_DANGEROUS_SCRIPT or --confirm-prod-apply. |
| billing-provider.cutover.preflight | metro billing-provider cutover preflight --collection-method=send_invoice|charge_automatically --reason="<why>" (--customer-id=|--external-id=|--ingest-alias=|--name=) [--old-config-id=] [--stripe-customer-id=] [--delivery-method-id=] [--leave-stripe-invoices-in-draft] (--sandbox|--prod) [--out=cutover.json] [--json] | billing-provider | preflight | live | read | metro.billing-provider-cutover.preflight.v1 | Live-read the customer's active Stripe billing-provider configuration, refuse if none/ambiguous or already on the requested method, reuse the existing stripe_customer_id/delivery_method_id unless overridden, and write an archiveCustomerBillingProviderConfigurations + setCustomerBillingProviderConfigurations [+ optional updateConfig leave_stripe_invoices_in_draft] payload with a confirm hash. Does not touch any contract - pair with contract move-plan/repair-accidental for the contract side. |
| billing-provider.cutover.apply | metro billing-provider cutover apply --file <cutover.json> (--sandbox|--prod) --confirm-hash <hash> [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] | billing-provider | apply | pack-op | write | metro.billing-provider-cutover.apply.v1 | Dry-run validates the cutover.json payload offline; live --apply optionally sets leave_stripe_invoices_in_draft, archives the old billing-provider configuration, sets the new one, then reads both back. Production requires ALLOW_DANGEROUS_SCRIPT or --confirm-prod-apply. |
| package.customers | metro package customers --package-id=<id>|--alias=<alias> (--sandbox|--prod) [--json] | package | read | live | read | metro.package-customers.v1 | Live-read which customers currently have an active contract on a package, given either a raw package id or its alias. Resolves each active contract to a customer (name, external id, ingest aliases). Does not cross into Stripe for email. |
| package.list | metro package list [--package-id=<id>|--alias=<alias>|--search=<text>] [--only-archived|--only-active] [--out=<file.json>] (--sandbox|--prod) [--json] | package | read | live | read | metro.package-list.v1 | Live-read inventory of every package version in the tenant, including archived ones, always following packages/list next_page to completion so the 100-row page size never truncates the result. Supports filtering by raw id, alias, or free-text search, and an optional --out dump to a local JSON file. |
| product.retire.preview.product-rate-retirement | metro product retire preview --file <input.json|yaml> (--sandbox|--prod) [--shape product-rate-retirement] [--json] | product | preview | local | none | metro.preview.v1 | Build a local product/rate retirement plan that closes affected rate-card entries before optional product archive, without calling Metronome. |
| rate-card.dimensional.preview | metro rate-card dimensional preview --file <input.json|yaml> (--sandbox|--prod) [--shape dimensional-rate-card] [--json] | rate-card | preview | local | none | metro.preview.v1 | Build a local dimensional rate-card plan for one action-code USAGE product plus per-action addRates entries, without calling Metronome. |
| invoice.issue-date.preview | metro invoice issue-date preview --file <input.json|yaml> (--sandbox|--prod) [--shape invoice-issue-date-update] [--json] | invoice | preview | local | none | metro.preview.v1 | Build a local DRAFT invoice issue-date update plan with explicit Stripe behavior, contract-end evidence, and read-back checks, without calling Metronome. |
| subscription.contract.preview.direct | metro subscription contract preview --file <input.json|yaml> (--sandbox|--prod) [--shape direct-subscription-contract] [--json] | subscription | preview | local | none | metro.preview.v1 | Build a local direct subscription contract plan with rate-card identity, frequency, quantity/seat source, billing-provider, and read-back checks, without calling Metronome. |
| custom-contract.preview.enterprise | metro custom-contract preview --file <input.json|yaml> (--sandbox|--prod) [--shape enterprise-custom-contract] [--json] | custom-contract | preview | local | none | metro.preview.v1 | Build a local direct enterprise custom-contract plan with explicit customer identity, Stripe billing-provider config, recurring commit, optional bonus commits, optional seat updates, side-effect summary, read-back plan, and canonical hash. |
| usage.ingest.preview | metro usage ingest preview --file <input.json|yaml> (--sandbox|--prod) [--shape usage-ingest-preview] [--json] | usage | preview | local | none | metro.preview.v1 | Build a local usage ingest preview plan with event-shape validation, transaction-id idempotency, invoice-period risk review, canary gating, and read-back checks, without calling Metronome. |
| api.catalog | metro api catalog [--family <family>] [--json] | api | explain | local | none | metro.api.catalog.v1 | List reviewed Metronome endpoint IDs, methods, paths, support status, source IDs, and local-only live-execution state. |
| api.explain | metro api explain <endpoint-id> [--json] | api | explain | local | none | metro.api.endpoint.v1 | Explain one reviewed endpoint contract, including operation type, permission scope, request/response contract, gates, current workflow commands, and sources. |
| api.search | metro api search <query> [--query <text>] [--family <family>] [--json] | api | explain | local | none | metro.api.search.v1 | Search reviewed endpoint IDs, titles, methods, paths, summaries, source IDs, policy gates, and command text without loading API clients. |
| api.diff | metro api diff <left-endpoint-id> <right-endpoint-id> [--json] | api | explain | local | none | metro.api.diff.v1 | Compare two reviewed endpoint contracts by endpoint ID, including local method/path metadata, request and response contracts, policy gates, command coverage, source IDs, and disabled live-execution state. |
| api.export | metro api export [--family <family>] [--json] | api | export | local | none | metro.api.export.v1 | Export a source-linked local documentation bundle for reviewed API endpoint docs, command docs, workflow shape docs, validator rules, gotchas, approval policies, and checked-in example fixtures without loading API clients. |
| api.scopes | metro api scopes [--family <family>] [--json] | api | explain | local | none | metro.api.permission-scopes.v1 | List expert API permission scopes derived from the reviewed endpoint catalog, including access class, endpoint coverage, approval model, live-execution status, and required gates. |
| api.approvals | metro api approvals [--family <family>] [--json] | api | explain | local | none | metro.api.approval-policies.v1 | List local expert API approval policies by permission scope, including accountable owner role, required approver roles, approval record fields, evidence requirements, confirmation requirement, and disabled live-execution status. |
| api.readiness | metro api readiness [--family <family>] [--summary] [--json] | api | explain | local | none | metro.api.readiness.v1 | Summarize reviewed read and write endpoint readiness, including compact gap counts with --summary, endpoint-specific validator coverage, local read-plan coverage, write proof-ladder coverage, and disabled live-read/write status. |
| api.validate | metro api validate <endpoint-id> --file <request.json|yaml> [--json] | api | validate | local | none | metro.api.validation.v1 | Validate a local expert API request file against a reviewed endpoint id, source-linked contract, permission scope, and endpoint-specific safety rules without loading API clients. |
| api.read-plan | metro api read-plan <endpoint-id> --file <request.json|yaml> (--sandbox|--prod) [--json] | api | inspect-plan | local | none | metro.api.read-plan.v1 | Build a local expert API read plan for a reviewed read endpoint, including explicit tenant, endpoint-specific request validation, request hash, future confirm-live-read gate, and stable output contract without loading API clients. |
| api.read-preflight | metro api read-preflight <endpoint-id> --file <request.json|yaml> (--sandbox|--prod) [--read-gate <api-read-gate.json>] [--confirm-live-read <token>] [--json] | api | explain | local | none | metro.api.read-preflight.v1 | Build a local expert API read preflight summary that combines endpoint selection, explicit tenant, request validation, local read-plan evidence, optional read-gate validation, live-read authorization evidence, and remaining runtime blockers without loading API clients. |
| api.read-gate.template | metro api read-gate template --read-plan <api-read-plan.json> [--profile-resolution <profile-resolution.json>] [--profile <profile>] [--key-env <env>] [--key-fingerprint <fingerprint>] [--authorization-id <id>] [--approved-by <name>] [--audit-log <path>] [--json] | api | explain | local | none | metro.api.read-gate.v1 | Build a local expert API read-gate manifest that binds a reviewed read-plan file hash to tenant profile-resolution evidence, current-turn authorization, audit-safe request summary rules, and stable output verification without enabling live reads. |
| api.read-gate.validate | metro api read-gate validate --file <api-read-gate.json> [--json] | api | validate | local | none | metro.api.read-gate.validation.v1 | Validate local expert API read-gate evidence for read-plan hash binding, tenant profile, current-turn authorization, audit-safe summaries, read-only runner requirements, and output verification while live reads remain disabled. |
| api.read-result.verify | metro api read-result verify --file <api-read-result.json> [--json] | api | verify | local | none | metro.api.read-result.validation.v1 | Validate mocked expert API read output for read-gate binding, request hash, mocked transport, response hash, read-only request summary, and response-contract checks without enabling live reads. |
| api.read-mock | metro api read-mock <endpoint-id> --file <request.json|yaml> --read-gate <api-read-gate.json> --mock-response <response-data.json> [--actor <id>] [--json] | api | verify | local | none | metro.api.read-mock.v1 | Run the local mocked expert API read pipeline for a reviewed endpoint, binding request input to a read gate, mocked response data to read-result verification, and a read-audit template without live API access. |
| api.read-pipeline | metro api read-pipeline <endpoint-id> --file <request.json|yaml> --read-gate <api-read-gate.json> --mock-response <response-data.json> --out <api-read-audit.jsonl> --actor <id> (--dry-run|--write) [--timestamp <ISO>] [--json] | api | audit | local | none | metro.api.read-pipeline.v1 | Run the local mocked expert API read pipeline and prepare or append the read-audit JSONL row in one step, using reviewed endpoint IDs, read-gate evidence, mocked response data, explicit actor, and explicit local audit output while live reads remain disabled. |
| api.read-audit.template | metro api read-audit template --read-gate <api-read-gate.json> --read-result <api-read-result.json> [--actor <id>] [--json] | api | explain | local | none | metro.api.read-audit.template.v1 | Build a local JSONL read-audit row template from validated read-gate and mocked read-result evidence, with request hashes, response hashes, key fingerprints, and audit-safe summaries only. |
| api.read-audit.write | metro api read-audit write --read-gate <api-read-gate.json> --read-result <api-read-result.json> --out <api-read-audit.jsonl> --actor <id> (--dry-run|--write) [--timestamp <ISO>] [--json] | api | audit | local | none | metro.api.read-audit.write.v1 | Build and optionally append one local expert API read-audit JSONL row from validated read-gate and mocked read-result evidence, requiring an explicit output path, actor, and dry-run or write mode while live reads remain disabled. |
| api.read-audit.validate | metro api read-audit validate --file <api-read-audit.jsonl> [--json] | api | validate | local | none | metro.api.read-audit.validation.v1 | Validate local expert API read-audit JSONL for read-gate binding, key fingerprints, read-only request summaries, response hashes, verification status, and secret-free evidence. |
| api.read | metro api read <endpoint-id> --file <request.json|yaml> (--sandbox|--prod) --read-gate <api-read-gate.json> --confirm-live-read <token> [--json] | api | read | live-guarded | read | metro.api.read-result.v1 | Execute a guarded live Metronome read for reviewed endpoints when read-gate evidence, current-turn authorization, and tenant key configuration are satisfied. Supported: contracts.get.v2, customers.get, invoices.listForCustomer. |
| api.apply | metro api apply <endpoint-id> --file <request.json|yaml> --sandbox --apply-gate <api-apply-gate.json> --approval-record <api-approval-record.json> --confirm-live-apply <token> [--json] | api | apply | live-guarded | write | metro.api.apply-live-result.v1 | Execute a guarded live sandbox Metronome write when apply-gate and approval-record evidence match. Currently limited to contracts.create in sandbox only. |
| api.preview | metro api preview <endpoint-id> --file <request.json|yaml> (--sandbox|--prod) [--json] | api | preview | local | none | metro.api.preview.v1 | Build a local expert API preview contract with explicit tenant, endpoint-specific validation, source-linked request summary, policy gates, and a stable preview hash without loading API clients. |
| api.preflight.template | metro api preflight template --preview <api-preview.json> [--profile-resolution <profile-resolution.json>] [--approval-id <id>] [--json] | api | explain | local | none | metro.api.preflight.v1 | Build a local expert API preflight template that binds a metro.api.preview.v1 output to tenant profile-resolution evidence, approval, audit, idempotency, sandbox proof, canary, read-back, and rollback evidence before any future expert apply. |
| api.preflight.validate | metro api preflight validate --file <api-preflight.json> [--json] | api | validate | local | none | metro.api.preflight.validation.v1 | Validate local expert API preflight evidence for preview-hash binding, endpoint source proof, permission scope, tenant profile-resolution evidence, approval, idempotency, audit, sandbox proof, canary, read-back, and rollback before any future expert apply. |
| api.sandbox-proof.template | metro api sandbox-proof template --preview <api-preview.json> --preflight <api-preflight.json> [--reviewed-by <reviewer>] [--owner <owner>] [--json] | api | explain | local | none | metro.api.sandbox-proof.v1 | Build a local expert API sandbox-proof template that binds a sandbox API preview and preflight to canary, read-back, invoice/Stripe behavior, and rollback/remediation evidence without enabling expert API apply. |
| api.sandbox-proof.validate | metro api sandbox-proof validate --file <api-sandbox-proof.json> [--json] | api | validate | local | none | metro.api.sandbox-proof.validation.v1 | Validate local expert API sandbox-proof evidence for reviewed sandbox tenant, preview/preflight hash binding, canary result, read-back, invoice/Stripe behavior, rollback, and disabled expert API apply state. |
| api.apply-gate.template | metro api apply-gate template --preview <api-preview.json> --preflight <api-preflight.json> [--sandbox-proof <sandbox-proof.json>] [--profile-resolution <profile-resolution.json>] [--approval-id <id>] [--owner <owner>] [--key-env <env>] [--key-fingerprint <fingerprint>] [--audit-log <path>] [--json] | api | explain | local | none | metro.api.apply-gate.v1 | Build a local expert API apply-gate manifest that file-hashes reviewed API preview, API preflight, sandbox proof, tenant profile-resolution, approval, key fingerprint, audit, verification, rollback, and idempotency evidence without enabling expert API apply. Production gates bind sandbox proof by reviewed endpoint id and request hash while binding approval to the production preview hash. |
| api.apply-gate.validate | metro api apply-gate validate --file <api-apply-gate.json> [--json] | api | validate | local | none | metro.api.apply-gate.validation.v1 | Validate a local expert API apply-gate manifest and referenced preview, preflight, sandbox-proof, and tenant profile-resolution files before any future expert API apply runner can use the evidence, including production-to-sandbox proof binding by request hash. |
| api.approval-record.template | metro api approval-record template --apply-gate <api-apply-gate.json> [--approval-id <id>] [--requested-by <id>] [--approved-by <name>] [--owner <owner>] [--business-purpose <text>] [--expires-at <ISO>] [--json] | api | explain | local | none | metro.api.approval-record.v1 | Build a durable local expert API approval record from a validated API apply-gate file hash, preserving reviewed preview, sandbox-proof, tenant profile, audit, read-back, rollback, idempotency, and owner approval evidence without serving as current-turn authorization or enabling expert API apply. |
| api.approval-record.validate | metro api approval-record validate --file <api-approval-record.json> [--json] | api | validate | local | none | metro.api.approval-record.validation.v1 | Validate a durable local expert API approval record against the referenced apply-gate file hash, endpoint policy, approval metadata, tenant profile, sandbox proof, rollback, idempotency, and disabled-live-apply state before it can be used as future evidence. |
| api.apply-audit.template | metro api apply-audit template --approval-record <api-approval-record.json> [--actor <id>] [--json] | api | explain | local | none | metro.api.apply-audit.template.v1 | Build a local planned expert API apply-audit row from a validated approval-record file, carrying approval, apply-gate, tenant profile, idempotency, rollback, and read-back evidence without claiming current-turn authorization or enabling expert API apply. |
| api.apply-audit.write | metro api apply-audit write --approval-record <api-approval-record.json> --out <api-apply-audit.jsonl> --actor <id> (--dry-run|--write) [--timestamp <ISO>] [--json] | api | audit | local | none | metro.api.apply-audit.write.v1 | Prepare or append one local planned expert API apply-audit JSONL row after approval-record validation, using explicit dry-run/write mode and append-only local output while live expert API apply remains disabled. |
| api.apply-audit.validate | metro api apply-audit validate --file <api-apply-audit.jsonl> [--json] | api | validate | local | none | metro.api.apply-audit.validation.v1 | Validate local planned expert API apply-audit JSONL rows for approved approval-record binding, apply-gate hashes, tenant profile, read-back plan, rollback, idempotency, and disabled-live-apply state. |
| api.apply-readback.verify | metro api apply-readback verify --apply-audit <api-apply-audit.jsonl> --read-result <api-read-result.json> [--row <n>] [--json] | api | verify | local | none | metro.api.apply-readback.verify.v1 | Compare local planned expert API apply-audit read-back checks with verified mocked read-result evidence, binding read-back proof without claiming live apply execution, live read execution, or current-turn authorization. |
| api.apply-result.template | metro api apply-result template --apply-audit <api-apply-audit.jsonl> --apply-readback <api-apply-readback.json> [--row <n>] [--json] | api | template | local | none | metro.api.apply-result.template.v1 | Build a local expert API apply-result contract template from planned apply-audit and compatible apply-readback evidence without enabling live apply. |
| api.apply-result.validate | metro api apply-result validate --file <api-apply-result.json> --apply-audit <api-apply-audit.jsonl> --apply-readback <api-apply-readback.json> [--row <n>] [--json] | api | verify | local | none | metro.api.apply-result.validation.v1 | Validate a local expert API apply-result evidence file for endpoint binding, guarded execution metadata, response object IDs, semantic read-back success, rollback, idempotency, and secret-free evidence. |
| docs.command-reference | metro docs command-reference [--json|--html|--markdown] | docs | explain | local | none | metro.docs.command-reference.v1 | Print the command and output contract catalog as machine-readable JSON, Markdown, or generated HTML. |
| docs.schema | metro schema [--json] | docs | explain | local | none | metro.docs.command-reference.v1 | Print the same machine-readable command, output, status, and exit-code catalog from a top-level automation-friendly command. |
| docs.explain | metro docs explain <topic> [--topic <topic>] [--list] [--json|--html|--markdown] | docs | explain | local | none | metro.docs.explain.v1 | Explain one source-linked documentation topic, list available docs-explain topic families, or render the topic index as generated HTML from local references, including reviewed endpoint IDs, workflow shapes, validator rules, gotchas, permission scopes, command IDs, checked-in example fixtures, and curated operating topics without loading API clients. |
| docs.api-reference | metro docs api-reference [--family <family>] [--json|--html|--markdown] | docs | explain | local | none | metro.docs.api-reference.v1 | Print the generated reviewed endpoint catalog reference with endpoint IDs, request/response contracts, permission scopes, gates, sources, and local-only execution state. |
| docs.evidence-gate-reference | metro docs evidence-gate-reference [--json|--html|--markdown] | docs | explain | local | none | metro.docs.evidence-gate-reference.v1 | Print the generated evidence-gate reference for preview-only write shapes, including preflight, audit, sandbox-proof, apply-gate coverage, blocked apply commands, source modules, and local-only execution state. |
| docs.input-reference | metro docs input-reference [--json|--html|--markdown] | docs | explain | local | none | metro.docs.input-reference.v1 | Print the generated structured input reference with JSON/YAML adapter scope, metro.input.normalize.v1 output fields, round-trip guarantees, secret-scan behavior, and source-linked proof commands. |
| docs.shape-reference | metro docs shape-reference [--json|--html|--markdown] | docs | explain | local | none | metro.docs.shape-reference.v1 | Print the generated shape catalog reference with required input, maturity, blocked modes, validator rules, and sources. |
| docs.validator-reference | metro docs validator-reference [--json|--html|--markdown] | docs | explain | local | none | metro.docs.validator-reference.v1 | Print the generated validator rule reference with severity, remediation, and shape mappings. |
| docs.gotcha-reference | metro docs gotcha-reference [--json|--html|--markdown] | docs | explain | local | none | metro.docs.gotcha-reference.v1 | Print the generated gotcha-to-validator coverage reference with current rules, planned rules, gaps, and sources. |
| setup.quickstart | metro setup quickstart [--json|--shell] | setup | explain | local | none | metro.setup.quickstart.v1 | Print the first safe preview path for a new teammate: temp sample files, command schema discovery, profile template, profile resolution, local validation, sandbox preview, expected output cues, a copy/paste shell block, and safety boundaries without live API access. |
| harness.list | metro harness list [--json] | harness | explain | local | none | metro.harness.list.v1 | List local harness suites for onboarding, fixture proof, workspace intent plans, and live allowlist audits. |
| harness.run | metro harness run --suite <onboard|local|workspace|live-allowlist> [--execute] [--fixture-root <path>] [--json] | harness | validate | local | none | metro.harness.v1 | Build or execute a local harness suite that proves CLI onboarding, fixtures, workspace plans, or allowlist catalog coverage without live Metronome access. |
| harness.intent | metro harness intent <intent> (--sandbox|--prod) [--out <dir>] [--execute] [--json] | harness | preview | local | none | metro.harness.v1 | Plan → template → validate/preview ladder for one workspace billing intent. |
| harness.read | metro harness read <endpoint-id> --file <request.json> (--sandbox|--prod) [--execute] [--json] | harness | validate | local | none | metro.harness.v1 | Local read proof ladder: validate → read-plan for a reviewed read endpoint without calling Metronome. |
| harness.apply | metro harness apply <endpoint-id> --file <request.json> [--execute] [--json] | harness | validate | local | none | metro.harness.v1 | Local sandbox write proof ladder: validate → preview for a reviewed write endpoint without live apply. |
| mode.show | metro mode [show] [--json] | setup | explain | local | none | metro.operator-mode.v1 | Show the sticky operator mode ceiling (local-only | read-only | read-write) stored in ~/.metro/mode.json. Does not authorize any live call by itself. |
| mode.set | metro mode set <local-only|read-only|read-write> [--json] | setup | validate | local | none | metro.operator-mode.v1 | Persist the operator mode ceiling until changed. read-only allows live lookups; read-write allows allowlisted writes (confirmation tokens still required). |
| mode.reset | metro mode reset [--json] | setup | validate | local | none | metro.operator-mode.v1 | Remove ~/.metro/mode.json and restore the default ceiling (read-only). Raise it with metro mode set read-write only for an approved write. |
| install.doctor | metro doctor [--json] | setup | validate | local | none | metro.install.doctor.v1 | Check global metro install health: PATH, npm link target, broken git+ symlinks, ~/.metro/src checkout, and optional gh auth. Prints the canonical install one-liner when something is wrong. |
| status.dashboard | metro status [--file <profiles.json>] [--profile <name>] [--check-env] [--json] | setup | explain | local | none | metro.status.v1 | Print a local dashboard combining operator mode, workspace model summary, optional profile auth check, live endpoint allowlist, and compact API readiness. |
| setup.init | metro setup init [--dir <path>] [--write] [--force] [--json] | setup | validate | local | none | metro.setup.init.v1 | Plan or write ~/.metro/profiles.json from the local profile template without loading API clients or printing secrets. |
| setup.template | metro setup template [--json] | setup | explain | local | none | metro.profiles.v1 | Print a local profile template with tenant-scoped Metronome key environment variable names. |
| setup.doctor | metro setup doctor --file <profiles.json> [--json] | setup | validate | local | none | metro.setup.doctor.v1 | Validate a local profile file and report environment variable presence by name only without loading API clients. |
| setup.auth | metro setup auth --file <profiles.json> [--profile <name>] [--check-env] [--json] | setup | validate | local | none | metro.setup.auth.v1 | Check profile key env var presence and list the current live read/sandbox-apply endpoint allowlist without printing secret values. |
| setup.resolve | metro setup resolve --file <profiles.json> --profile <name> --key-fingerprint <fingerprint> [--expect-tenant <tenant>] [--check-env] [--json] | setup | validate | local | none | metro.profile.resolve.v1 | Resolve one named tenant profile into secret-free local binding evidence for future read gates or preflight manifests without authorizing live API access. |
| release.readiness | metro release readiness [--json] | release | explain | local | none | metro.release.readiness.v1 | Print a local release readiness report for the Node package: package/install proof, publish blockers, refused assumptions, required registry/provenance/approval/versioning/integrity evidence, and disabled live/npm-registry access. |
| release.artifact-manifest | metro release artifact-manifest [--json] | release | explain | local | none | metro.release.artifact-manifest.v1 | Print a local release artifact manifest describing recommended CI/release evidence files, source commands, retention ownership, blocked publish/token/registry actions, and remaining release-policy open questions without writing files. |
| release.evidence-check | metro release evidence-check --dir <artifact-directory> [--json] | release | validate | local | none | metro.release.evidence-check.v1 | Validate an operator-supplied local release evidence directory against the artifact manifest by checking required files, JSON schemaVersion fields, and log file presence without writing artifacts, reading .env, loading tokens, touching npm registry state, or authorizing publish. |
| release.evidence-plan | metro release evidence-plan --policy <policy.json|yaml> [--json] | release | explain | local | none | metro.release.evidence-plan.v1 | Plan manual release evidence capture from a validated retention policy and artifact manifest without creating directories, writing artifacts, reading .env, loading tokens, touching npm registry state, or authorizing publish. |
| release.retention-policy.template | metro release retention-policy template [--json] | release | template | local | none | metro.release.retention-policy.v1 | Print a local release evidence retention policy template for documenting the reviewed artifact directory, retention period, owner, approver, access model, cleanup cadence, allowed filenames, required checks, and blocked publish/live actions before any artifact-writing command exists. |
| release.retention-policy.validate | metro release retention-policy validate --file <policy.json|yaml> [--json] | release | validate | local | none | metro.release.retention-policy.validation.v1 | Validate a reviewed local release evidence retention policy before future artifact writers can use it, rejecting source-tree artifact directories, placeholder review fields, missing required artifact filenames, missing local checks, and missing blocked-action acknowledgements. |
| source-boundary.template | metro source-boundary template [--workflow <workflow>] [--shape <shape>] [--json] | source-boundary | explain | local | none | metro.source-boundary.v1 | Print a local manifest template for proving workflow inputs use current source files, generated artifacts as evidence-only, and no one-off command handlers. |
| source-boundary.validate | metro source-boundary validate --file <source-boundary.json> [--json] | source-boundary | validate | local | none | metro.source-boundary.validation.v1 | Validate local source-boundary evidence so future workflow inputs do not promote one-off scripts, depend on generated artifacts as source, or revive a previous billing system as a current integration. |
| preflight.template | metro preflight template --workflow <workflow> --shape <shape> [--sandbox|--prod] [--json] | preflight | explain | local | none | metro.preflight.v1 | Print a local apply-preflight template for a supported future apply workflow. |
| preflight.validate | metro preflight validate --file <preflight.json> [--json] | preflight | validate | local | none | metro.preflight.validation.v1 | Validate an apply-preflight file before any future apply workflow can be approved. |
| apply-gate.template | metro apply-gate template --workflow <workflow> --shape <shape> [--sandbox|--prod] [--json] | apply-gate | explain | local | none | metro.apply-gate.v1 | Print a local apply gate manifest tying preview hash, preflight, sandbox proof, approval, key fingerprint, audit, verification, rollback, and idempotency evidence together without enabling apply. |
| apply-gate.validate | metro apply-gate validate --file <apply-gate.json> [--json] | apply-gate | validate | local | none | metro.apply-gate.validation.v1 | Validate a local apply gate manifest and referenced preflight/proof files before any future apply runner can use the evidence. |
| approval-record.template | metro approval-record template --apply-gate <apply-gate.json> [--approval-id <id>] [--requested-by <id>] [--approved-by <name>] [--owner <owner>] [--business-purpose <text>] [--expires-at <ISO>] [--json] | approval-record | explain | local | none | metro.workflow.approval-record.v1 | Build a durable local workflow approval record from a validated apply-gate file hash, preserving reviewed preview, preflight, sandbox proof, audit, read-back, rollback, idempotency, and owner approval evidence without serving as current-turn authorization or enabling workflow apply. |
| approval-record.validate | metro approval-record validate --file <workflow-approval-record.json> [--json] | approval-record | validate | local | none | metro.workflow.approval-record.validation.v1 | Validate a durable local workflow approval record against the referenced apply-gate file hash, approval metadata, sandbox proof, audit destination, rollback, idempotency, and disabled-live-apply state before future workflow apply evidence can use it. |
| apply-readback.verify | metro apply-readback verify --audit <audit.jsonl> (--inspect-output <inspect-output.json>|--inspect-outputs <inspect-output-a.json,inspect-output-b.json>) [--row <n>] [--json] | apply-readback | verify | local | none | metro.workflow.apply-readback.verify.v1 | Compare local workflow apply audit verification checks with one or more verified inspect-output evidence files, binding read-back proof without enabling live reads, live apply, or current-turn authorization. |
| audit.template | metro audit template --workflow <workflow> --shape <shape> [--sandbox|--prod] [--json] | audit | explain | local | none | metro.audit.template.v1 | Print a local JSONL audit-row template for a supported future apply workflow. |
| audit.validate | metro audit validate --file <audit.jsonl> [--json] | audit | validate | local | none | metro.audit.validation.v1 | Validate local audit JSONL rows for required evidence fields, hashes, verification status, and secret-free content. |
| audit.write | metro audit write --file <audit-rows.jsonl> --out <audit.jsonl> (--dry-run|--write) [--json] | audit | audit | local | none | metro.audit.write.v1 | Validate and optionally append local workflow audit JSONL rows to an explicit append-only destination while workflow apply remains disabled. |
| proof.sandbox-template | metro proof sandbox-template --workflow <workflow> --shape <shape> [--json] | proof | explain | local | none | metro.sandbox-proof.v1 | Print a sandbox-proof manifest template for a supported future write workflow without enabling apply. |
| proof.validate | metro proof validate --file <sandbox-proof.json> [--json] | proof | validate | local | none | metro.sandbox-proof.validation.v1 | Validate a local sandbox-proof manifest for preview, preflight, audit, canary, read-back, rollback, idempotency, and production-block evidence. |
| customer.billing-state.plan | metro customer billing-state --customer-id <id> (--sandbox|--prod) --plan [--json] | customer | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for customer billing state, including customer, billing-provider, contract, balance, and invoice endpoints. |
| package.inspect.plan | metro package inspect --alias <package_alias> (--sandbox|--prod) --plan [--json] | package | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for package alias inspection, package get, and contracts-on-package checks without loading a Metronome API client. |
| product.inspect.plan | metro product inspect --product-id <id> (--sandbox|--prod) --plan [--json] | product | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for product current, initial, archived, and scheduled-update state without loading a Metronome API client. |
| billing-provider.inspect.plan | metro billing-provider inspect --customer-id <id> (--sandbox|--prod) --plan [--json] | billing-provider | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for customer billing provider configuration without loading a Metronome API client. |
| contract.inspect.plan | metro contract inspect --contract-id <id> (--sandbox|--prod) --plan [--at <timestamp>] [--json] | contract | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for contract inspection without loading a Metronome API client. |
| invoice.inspect.plan | metro invoice inspect --invoice-id <id> (--sandbox|--prod) --plan [--json] | invoice | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for invoice and payment inspection without loading a Metronome API client. |
| subscription.history.inspect.plan | metro subscription history inspect --customer-id <id> --contract-id <id> --subscription-id <id> (--sandbox|--prod) --plan [--json] | subscription | inspect-plan | local | none | metro.inspect.plan.v1 | Build a local read plan for subscription quantity and seat history inspection without loading a Metronome API client. |
| verify.inspect-output | metro verify inspect-output --file <inspect-output.json> [--json] | verify | verify | local | none | metro.verify.inspect-output.v1 | Validate a local inspect output JSON file as reusable verification evidence without making live reads. |
| verify.audit-log | metro verify --audit-log <audit.jsonl> [--json] | verify | verify | local | none | metro.verify.audit-log.v1 | Validate a local workflow audit JSONL file, summarize write outcomes and read-back verification status, and keep live execution disabled. |
| verify.apply-result | metro verify apply-result --file <apply-result.json> [--json] | verify | verify | local | none | metro.verify.apply-result.v1 | Validate a local apply result JSON file for preview hash binding, workflow evidence bundles, preflight, audit log, write summaries, read-back checks, rollback, idempotency, and secret-free evidence. |
| verify.apply-result-template | metro verify apply-result-template --workflow <workflow> --shape <shape> [--sandbox|--prod] [--json] | verify | template | local | none | metro.verify.apply-result.template.v1 | Print a local workflow apply-result evidence template with required workflow evidence bundles, writes, optional skipped rows, read-back checks, and disabled live-apply state. |
| ops.list | metro ops [--json] | ops | explain | local | none | metro.ops.list.v1 | Show the pack-aware one-liner cookbook for recurring ops asks (lookups, plans, credits), each mapped to the exact command for the active workspace pack. |
| ops.who | metro ops who <name|uuid|email|external-id|url> (--sandbox|--prod) [--json] | ops | read | live-read | read | metro.ops.who.v1 | One-shot customer snapshot: resolve whatever was pasted, show active contract + credits, and print the next-step commands. Prefer this over separate resolve/billing-state/balances calls. |
| ops.log | metro ops log --ask="<what was asked>" [--source=slack|linear|verbal] [--minutes=<n>] [--file=docs/ops-log.md] [--json] | ops | template | local | none | metro.ops.log.v1 | Append an inbound one-off ask to the ops log (AGENTS.md Proof of Accuracy Rule #4) and flag ask shapes seen 3+ times as automation targets. |
| ops.top | metro ops top [--file=docs/ops-log.md] [--json] | ops | explain | local | none | metro.ops.top.v1 | Rank logged ask shapes by frequency and time spent; shapes with 3+ occurrences are flagged AUTOMATE. |
| customer.create.preflight | metro customer create preflight --name=<name> --ingest-alias=<alias>[,<alias>] [--external-id=<id> [--external-id-field=<key>]] [--custom-fields=<json>] [--stripe-customer-id=cus_... --stripe-collection-method=charge_automatically|send_invoice] [--file=<spec>] (--sandbox|--prod) [--json] | customer | preflight | pack-op | read | metro.op-plan.v1 | Plan POST /v1/customers. Proves every ingest alias is unused (the idempotency anchor; customer create has no uniqueness_key) and custom field keys exist. |
| customer.create.apply | metro customer create apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | customer | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| ratecard.create.preflight | metro ratecard create preflight --file=<ratecard.json|yaml> [--allow-alias-move] (--sandbox|--prod) [--json] | ratecard | preflight | pack-op | read | metro.op-plan.v1 | Plan rate-cards/create plus addRates (at most 100 rates per call). Refuses an existing card name or a live alias. |
| ratecard.create.apply | metro ratecard create apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | ratecard | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| ratecard.add-rates.preflight | metro ratecard add-rates preflight --rate-card-id=<id> --file=<rates.json|yaml> (--sandbox|--prod) [--json] | ratecard | preflight | pack-op | read | metro.op-plan.v1 | Plan addRates on an existing card; refuses rates that already exist. |
| ratecard.add-rates.apply | metro ratecard add-rates apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | ratecard | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| package.create.preflight | metro package create preflight --file=<package.json|yaml> [--allow-alias-takeover] (--sandbox|--prod) [--json] | package | preflight | pack-op | read | metro.op-plan.v1 | Plan POST /v1/packages/create from a spec; derives a uniqueness_key when omitted and refuses alias collisions. |
| package.create.apply | metro package create apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | package | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| package.clone-version.preflight | metro package clone-version preflight --aliases=<alias>[,<alias>] --handoff-at=<future UTC hour> [--usage-day=CONTRACT_START|FIRST_OF_MONTH] (--sandbox|--prod) [--json] | package | preflight | pack-op | read | metro.op-plan.v1 | Plan a new package version behind the same alias from the handoff hour; read-back proves the alias resolves to the old version before and the new one after. |
| package.clone-version.apply | metro package clone-version apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | package | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| contract.create.preflight | metro contract create preflight ((--package-alias=<alias>|--package-id=<id>) --starting-at=<UTC hour>|--file=<contract.json|yaml>) (--customer-id=|--external-id=|--ingest-alias=|--name=) [--allow-concurrent] (--sandbox|--prod) [--json] | contract | preflight | pack-op | read | metro.op-plan.v1 | Plan POST /v1/contracts/create from a package (pinned package_id) or a direct spec; refuses overlapping contracts. |
| contract.create.apply | metro contract create apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | contract | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| subscription.add.preflight | metro subscription add preflight (--file=<subscription.json|yaml>|--product-id=<id> --billing-frequency=<freq> --quantity=<n>) [--starting-at=<UTC hour>] (--customer-id=|...) [--contract-id=] (--sandbox|--prod) [--json] | subscription | preflight | pack-op | read | metro.op-plan.v1 | Plan /v2/contracts/edit add_subscriptions; requires a matching SUBSCRIPTION rate on the contract rate card. |
| subscription.add.apply | metro subscription add apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | subscription | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| subscription.set-quantity.preflight | metro subscription set-quantity preflight --subscription-id=<id> (--quantity=<n>|--delta=<n>) --starting-at=<UTC hour> (--customer-id=|...) (--sandbox|--prod) [--json] | subscription | preflight | pack-op | read | metro.op-plan.v1 | Plan /v2/contracts/edit update_subscriptions.quantity_updates with an absolute quantity. |
| subscription.set-quantity.apply | metro subscription set-quantity apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | subscription | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
| subscription.seats.preflight | metro subscription seats preflight --subscription-id=<id> --starting-at=<UTC hour> [--add-seat-ids=] [--remove-seat-ids=] [--add-unassigned=<n>] [--remove-unassigned=<n>] (--customer-id=|...) (--sandbox|--prod) [--json] | subscription | preflight | pack-op | read | metro.op-plan.v1 | Plan /v2/contracts/edit update_subscriptions.seat_updates for a SEAT_BASED subscription. |
| subscription.seats.apply | metro subscription seats apply --file <plan.json> --confirm-hash <sha256:...> (--sandbox|--prod) [--apply --confirm-live-apply=<token>|--confirm-prod-apply=<token>] [--json] | subscription | apply | pack-op | write | metro.op-apply.v1 | Dry run by default; --apply writes with the tenant typed token, then reads back and exits 3 on any expected-vs-actual mismatch. |
Unsupported commands
| id | command | group | mode | status | apiAccess | schemaVersion | description |
|---|---|---|---|---|---|---|---|
| package.apply | metro package apply --shape <shape> --file <input.json|yaml> (--sandbox|--prod) [--confirm-hash <hash>] | apply | unsupported | write | Apply is blocked until apply-grade payload builders, audit logs, sandbox proof, production hash confirmation, read-back verification, and a valid preflight exist. | ||
| package.archive.apply | metro package archive apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Package archive apply is blocked until replacement alias handoff evidence, sandbox proof, audit logs, production hash confirmation, read-back verification, rollback evidence, and owner approval exist. | ||
| customer.setup.apply | metro customer setup apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Customer setup apply is blocked until duplicate customer state, archived alias collision checks, sandbox proof, audit logs, production hash confirmation, read-back verification, invoice-side-effect proof, and owner approval exist. | ||
| product.retire.apply | metro product retire apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Product retirement apply is blocked until inspected rate schedules, sandbox proof, audit logs, production hash confirmation, read-back verification, rollback evidence, and owner approval exist. | ||
| rate-card.dimensional.apply | metro rate-card dimensional apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Dimensional rate-card apply is blocked until billable-metric compound group-key evidence, product duplicate-prevention evidence, sandbox canary proof, audit logs, production hash confirmation, rate schedule and invoice read-back verification, rollback evidence, and owner approval exist. | ||
| invoice.issue-date.apply | metro invoice issue-date apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Invoice issue-date apply is blocked until draft invoice state, contract end evidence, explicit Stripe behavior, sandbox proof, audit logs, production hash confirmation, read-back verification, remediation evidence, and owner approval exist. | ||
| subscription.contract.apply | metro subscription contract apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Direct subscription contract apply is blocked until subscription rate-card evidence, sandbox proof, audit logs, production hash confirmation, read-back verification, rollback evidence, and owner approval exist. | ||
| usage.ingest.apply | metro usage ingest apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Usage ingest apply is blocked until preview-events proof, canary support, audit logs, production hash confirmation, read-back verification, rollback evidence, and owner approval exist. | ||
| custom-contract.apply | metro custom-contract apply --file <input.json|yaml> (--sandbox|--prod) --confirm-hash <hash> | apply | unsupported | write | Custom-contract apply is blocked until inspected current state, sandbox proof, audit logs, production hash confirmation, read-back verification, rollback evidence, and owner approval exist. | ||
| api.read.legacy-blocked | metro api read <endpoint-id> (unsupported endpoint or missing evidence) | read | unsupported | read | Live read requires a supported endpoint, validated read gate, confirm-live-read token, and configured tenant key. See TEAM-QUICKSTART.md. | ||
| api.apply.legacy-blocked | metro api apply <endpoint-id> (production or unsupported endpoint) | apply | unsupported | write | Live apply is sandbox-only and limited to contracts.create with apply-gate and approval-record evidence. | ||
| customer.billing-state | metro customer billing-state --customer-id <id> (--sandbox|--prod) | inspect | unsupported | read | Live read execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. | ||
| contract.inspect | metro contract inspect --contract-id <id> (--sandbox|--prod) | inspect | unsupported | read | Live read execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. | ||
| package.inspect | metro package inspect --alias <package_alias> (--sandbox|--prod) | inspect | unsupported | read | Live package inspect execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. | ||
| product.inspect | metro product inspect --product-id <id> (--sandbox|--prod) | inspect | unsupported | read | Live product inspect execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. | ||
| billing-provider.inspect | metro billing-provider inspect --customer-id <id> (--sandbox|--prod) | inspect | unsupported | read | Live billing-provider inspect execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. | ||
| invoice.inspect | metro invoice inspect --invoice-id <id> (--sandbox|--prod) | inspect | unsupported | read | Live read execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. | ||
| subscription.history.inspect | metro subscription history inspect --customer-id <id> --contract-id <id> --subscription-id <id> (--sandbox|--prod) | inspect | unsupported | read | Live subscription history inspect execution is blocked until tenant-explicit guarded read clients exist. Use the --plan form for the local endpoint and output contract plan. |
Agent notes
- Prefer
--jsonwhen scripting parsers; use--markdownwhen loading context into an agent. - Never treat HTML as the source of truth, regenerate from
metro docs <ref> --markdown. - Live reads/writes still require tenant flags + confirmation tokens.