# metro

> metro is an open-source CLI and agent toolkit for Metronome billing, for any Metronome tenant. It is read-only by default. Every write goes preview, typed confirm hash, apply, then a read-back that compares expected and actual. Apache-2.0. Not affiliated with Metronome, Inc.

You are an agent. A human gave you this file to set up metro on their machine. Read all of it before you run anything, and follow the safety contract exactly. It is a brief for you, not marketing. After setup, `~/.metro/AGENTS.md` is your full operating manual.

## Safety contract (read first)

1. Read-only by default. After `metro init`, metro can look, preview and validate, but not change anything. Writes need `metro mode write` (long form `metro mode set read-write`), and only the human decides to raise it.
2. Sandbox first. Every change is proven on sandbox before production is discussed.
3. Always name the tenant: pass `--sandbox` or `--prod`. metro never picks production on its own.
4. Never ask the human to paste an API key into chat. If they paste one anyway, don't repeat it; tell them to revoke it and create a new one. Never `cat` or echo `~/.metro/.env`. metro prints key fingerprints, never values.
5. Preview before every write. Preview or preflight writes a local file and prints `payloadHash` (`sha256:…`). Show the human the plain-English change and the hash, then wait for their yes.
6. Apply only with `--confirm-hash <hash>` from the exact preview the human approved. Without `--apply` it is a dry run. If any input changed, preview again: a changed field means a new hash.
7. Production needs the human's explicit typed yes in chat for that specific change, plus `--prod --confirm-prod-apply=I_UNDERSTAND_BILLING_SIDE_EFFECTS`. Sandbox writes use `--confirm-live-apply=I_UNDERSTAND_THIS_WILL_WRITE_LIVE_METRONOME_SANDBOX`. A yes for one change never covers the next. A green preview is not authorization, and neither is a key being present.
8. After a live apply metro re-reads the object and fails on any mismatch. Report expected vs actual for every changed field. The readback is the proof.
9. Exit codes: `0` success, `1` validation failure, blocked plan or missing setup (fix the input, preview again), `2` safety refusal (stop, quote it to the human, don't work around it), `3` readback mismatch (the write landed but the object differs; read it fresh before anything else).
10. Don't retry a failed or interrupted apply blindly. Read the object back first, then tell the human what actually happened.

## Setup, by situation

### A. You are a local coding agent with a terminal (Claude Code, Codex, Cursor, or similar)

1. Install metro (Node 18+):
   ```
   git clone --depth 1 https://github.com/metrocli/metro.git ~/.metro/src && bash ~/.metro/src/scripts/install-global.sh
   ```
   Once npm publishing is live, `npm install -g @metrocli/metro` does the same.
2. Run `metro init --agent`. It never prompts. It creates `~/.metro/.env` (mode 600) with empty placeholders, puts metro in read-only mode, copies the manual to `~/.metro/AGENTS.md`, and prints:
   ```
   metro init (agent mode: no prompts)

   ✓ Created ~/.metro/.env (mode 600) with empty placeholders.

   ASK THE HUMAN TO DO THIS (do not ask them to paste keys into chat):
     1. Open https://app.metronome.com/sandbox/developer/api-tokens and create a token.
     2. Open ~/.metro/.env in an editor and paste it after METRONOME_SANDBOX_KEY=
     3. Save the file and tell you "done".

   Then run: metro init --check

   metro is in read-only mode. Operating manual: ~/.metro/AGENTS.md
   ```
3. Relay those three steps to the human. Sandbox tokens: https://app.metronome.com/sandbox/developer/api-tokens
4. When they say "done", run `metro init --check --json`. Continue only when `keys.sandbox.status` is `working`. Otherwise relay the `next` field verbatim and wait.
5. Read `~/.metro/AGENTS.md` before any change.
6. Production is optional and comes last. Only the human adds it, with `metro init --prod` or by editing the file. Production tokens: https://app.metronome.com/developer/api-tokens. Sandbox and production need separate tokens.

### B. You are a hosted chat assistant without a terminal

metro runs on the human's machine. Don't pretend to run commands. Tell the human: "metro needs a terminal. Open this in Claude Code, Codex or Cursor, or install it yourself: https://metrocli.com/docs/install/". Then stop.

### C. You are sandboxed and the network is blocked

If `github.com` or `api.metronome.com` can't be reached, don't retry in a loop. Tell the human which host was blocked and that metro needs it, then stop.

## Learn the tenant before you act

```
metro status --json                               # mode, keys, allowlists
metro catalog bind --sandbox --write              # products, rate cards, credit types into ~/.metro/profiles.json
metro tenant snapshot show --sandbox --markdown   # account pattern, catalog summary
metro ops who "<customer>" --sandbox              # one customer: contract, credits, balances
```

Reuse the bound catalog IDs. If something is missing, say so; don't invent IDs.

## Report a doorway, not an install log

When setup is done, don't paste logs. Reply with one line saying what the human can now do, then exactly three next actions. For example:

> metro is set up against your Metronome sandbox, in read-only mode.
> 1. Bind your sandbox catalog so I can name your real products: `metro catalog bind --sandbox --write`.
> 2. Look up your largest customer and show its contract and balances: `metro ops who "<name>" --sandbox`.
> 3. Preview one pricing change you've been meaning to make, on sandbox, with nothing applied.

Base the three actions on what you learned about this tenant.

## The loop for every change

1. **Preview.** `metro ledger-adjustment preflight --name="<customer>" --amount=500 --reason="<why>" --sandbox --out=ledger.json` writes the file and prints `payloadHash`.
2. **Confirm.** Show the change and the hash; wait for the human's explicit yes.
3. **Apply.** `metro ledger-adjustment apply --file ledger.json --sandbox --confirm-hash <hash>` is a dry run. Add `--apply --confirm-live-apply=I_UNDERSTAND_THIS_WILL_WRITE_LIVE_METRONOME_SANDBOX` to write. Writes also need `metro mode write`.
4. **Readback.** metro re-reads the object. Report expected vs actual for every changed field. A mismatch exits `3`: stop, read the object fresh, and don't re-run the same plan.

Other write workflows follow the same preflight → apply shape: `metro contract move-plan|extend-trial|expire`, `metro contract repair-accidental`, `metro billing-provider cutover`. Provisioning, same shape (`<cmd> preflight` then `<cmd> apply`): `metro customer create`, `metro ratecard create`, `metro ratecard add-rates`, `metro package create`, `metro package clone-version`, `metro contract create`, `metro subscription add`, `metro subscription set-quantity`, `metro subscription seats`. Offline plans: `metro plan list`.

## Metronome's API reference (source of truth)

metro's docs are the safety and workflow layer, not a copy of Metronome's API reference. For authoritative, current request and response details, read https://docs.metronome.com/llms.txt and the endpoint's page as markdown (append `.md` to any docs.metronome.com page URL). For what metro wraps, read https://metrocli.com/docs/reference/api-coverage.md: every documented endpoint, its Metronome page, and metro's status (op, catalog read, catalog write, not yet), checked 2026-11-03. If an endpoint is not yet wrapped, don't hand-roll a write to it; tell the human and link Metronome's page.

## Key pages

- Sandbox API tokens: https://app.metronome.com/sandbox/developer/api-tokens
- Production API tokens: https://app.metronome.com/developer/api-tokens
- Source: https://github.com/metrocli/metro

## Docs

Every page below is plain markdown. The full set in one file: https://metrocli.com/llms-full.txt

### Get started

- [Overview](https://metrocli.com/docs/index.md): What metro is, the safety ladder, and a 60-second read.
- [Install](https://metrocli.com/docs/install.md): Install metro with git clone and install-global.sh, then check it with metro doctor.
- [Keys: metro init](https://metrocli.com/docs/keys.md): Create ~/.metro/.env, add a sandbox key first, and an optional production key.
- [First sandbox read](https://metrocli.com/docs/first-sandbox-read.md): Your first read-only calls: metro status, catalog bind, ops who and package list against sandbox.

### Agents

- [Copy-paste setup](https://metrocli.com/docs/agents/copy-paste-setup.md): Give your agent one line. It installs metro, sets up your key file, and stops for you at every step that needs a human.
- [AGENTS.md](https://metrocli.com/docs/agents/agents-md.md): The operating manual metro ships for agents, section by section, with what each part makes your agent do.
- [llms.txt](https://metrocli.com/docs/agents/llms-txt.md): What's in /llms.txt and /llms-full.txt, and how every docs page has a plain markdown twin.
- [Safety contract](https://metrocli.com/docs/agents/safety-contract.md): Modes, tenant rules, refusals, confirm hashes, typed tokens, production rules and readback, as metro enforces them.

### Guides

- [Provision a package](https://metrocli.com/docs/guides/provision-a-package.md): Goal, preview, confirm, apply and readback for a new package.
- [Create a contract](https://metrocli.com/docs/guides/create-a-contract.md): Create a contract from a package, with preview and readback proof.
- [Plans and rate cards](https://metrocli.com/docs/guides/plans-and-rate-cards.md): Change plans and rate cards, including dimensional rate cards.
- [Subscriptions and seats](https://metrocli.com/docs/guides/subscriptions-and-seats.md): Add subscriptions and change quantities or seats on a contract.
- [Credits and commits](https://metrocli.com/docs/guides/credits-and-commits.md): Complimentary grants, paid top-ups and ledger adjustments.
- [Clone a package version](https://metrocli.com/docs/guides/clone-a-package-version.md): Publish a new package version behind the same aliases at a handoff hour.
- [Invoices](https://metrocli.com/docs/guides/invoices.md): Update an invoice issue date, with the Stripe expectations reviewed first.
- [Move a customer between plans](https://metrocli.com/docs/guides/move-a-customer.md): Move-plan preflight, then apply, one customer or in bulk.

### Concepts

- [Metronome architecture primer](https://metrocli.com/docs/concepts/architecture.md): Customer, contract, package, rate card, product and billable metric, with credits, commits and invoices.
- [Customers](https://metrocli.com/docs/concepts/customers.md): Customers, ingest aliases and how lookups work.
- [Billable metrics](https://metrocli.com/docs/concepts/billable-metrics.md): Usage events, aggregations and group keys.
- [Products](https://metrocli.com/docs/concepts/products.md): Usage, fixed and subscription products, and how they map to rates.
- [Rate cards](https://metrocli.com/docs/concepts/rate-cards.md): Rates, effective dates, rate types and dimensional rate cards.
- [Packages](https://metrocli.com/docs/concepts/packages.md): Reusable contract templates, aliases and versions.
- [Contracts](https://metrocli.com/docs/concepts/contracts.md): Contracts from packages or direct, transitions, overrides and end dates.
- [Credits & commits](https://metrocli.com/docs/concepts/credits-and-commits.md): Prepaid and postpaid commits, credits, access and invoice schedules, and the balance ledger.
- [Subscriptions & seats](https://metrocli.com/docs/concepts/subscriptions-and-seats.md): Recurring subscription charges, quantity, seat-based subscriptions and proration.
- [Invoices](https://metrocli.com/docs/concepts/invoices.md): Scheduled charges, finalization and voids.
- [Shapes and workspaces](https://metrocli.com/docs/concepts/shapes-and-workspaces.md): Why metro works in shapes, and sandbox versus production.

### Reference

- [Commands](https://metrocli.com/docs/reference/commands.md): Every metro command and its output contract.
- [Validators](https://metrocli.com/docs/reference/validators.md): The MTR validator codes and what each one checks.
- [Evidence gates](https://metrocli.com/docs/reference/evidence-gates.md): Workflow to shape to gate chain, for every write workflow.
- [Shapes](https://metrocli.com/docs/reference/shapes.md): The catalog of local shapes.
- [Inputs](https://metrocli.com/docs/reference/inputs.md): Input normalization and deterministic hashing.
- [API catalog](https://metrocli.com/docs/reference/api-catalog.md): The hand-curated Metronome endpoint catalog metro knows.
- [Metronome API coverage](https://metrocli.com/docs/reference/api-coverage.md): Every endpoint documented at docs.metronome.com, linked to its page, with what metro wraps.
- [Explain](https://metrocli.com/docs/reference/explain.md): The topics behind metro docs explain.
- [Gotchas](https://metrocli.com/docs/reference/gotchas.md): Known Metronome gotchas and the rules that cover them.
- [Changelog](https://metrocli.com/docs/reference/changelog.md): Metronome upstream changes and metro coverage.

## Optional

- [Agent manual](https://github.com/metrocli/metro/blob/main/AGENTS.md): the full operating manual (also at ~/.metro/AGENTS.md after init).
- [Safety policy](https://github.com/metrocli/metro/blob/main/docs/SAFETY.md)
- [Agent skill](https://github.com/metrocli/metro/blob/main/skills/metro/SKILL.md)
- [README](https://github.com/metrocli/metro#readme): the repo overview.
- [Metronome docs](https://docs.metronome.com/): the source of truth for Metronome's model. Machine-readable index: https://docs.metronome.com/llms.txt
- [Full docs](https://metrocli.com/llms-full.txt): every docs page concatenated, in nav order.