# Overview

> What metro is, the safety ladder, and a 60-second read.

Source: https://metrocli.com/docs/ · Docs index: https://metrocli.com/llms.txt

metro is an open-source CLI and agent toolkit for Metronome billing. It works with any Metronome tenant. You, or an agent like Claude Code, Codex or Cursor, use it to read your billing setup and change it safely.

metro reads first. Every change becomes a local plan file with a `sha256:` hash. You confirm that exact hash, metro applies it, then it reads the object back and prints expected vs actual.

## The 60-second read

- **What it is.** A terminal CLI, `metro`, plus an operating manual for agents (`AGENTS.md`) and an index of these docs for agents (`llms.txt`). Apache-2.0, Node 18 or newer.
- **What it touches.** Customers, rate cards, packages, contracts, subscriptions and seats, credits and commits, invoices. See the [architecture primer](/docs/concepts/architecture).
- **Where your keys live.** In `~/.metro/.env`, mode 600, outside every repo. You paste them in your editor. They never go through chat.
- **What it does by default.** Nothing that writes. After `metro init`, metro is read-only.
- **How a change lands.** Preflight, dry run, apply, readback. A readback mismatch exits `3`.
- **Not affiliated with Metronome, Inc.** metro is built for Metronome. Metronome's own docs at [docs.metronome.com](https://docs.metronome.com) are the source of truth for its model.

## The safety ladder

Six steps sit between your agent and production. All of them are on by default, and metro enforces them in code.

**Read-only.** metro starts unable to change anything. Writes are a mode you turn on: `metro mode write` (long form `metro mode set read-write`). Drop back with `metro mode set read-only`.

**Sandbox first.** Every live command takes `--sandbox` or `--prod`. metro never picks production on its own. Production needs its own key and its own flag.

**Preview.** A preflight reads Metronome, writes a local plan file with the exact request bodies, and prints its `payloadHash`. Nothing has been sent.

**Typed confirm.** Applying needs `--confirm-hash` with the hash of the exact preview you saw. Edit one field and apply refuses (`MTR-PLAN-002`). A live write also needs a typed token for the tenant.

**Apply.** `--apply` sends exactly the planned requests to the tenant you named. Writes are retried only on HTTP 429, so a timed-out create is never sent twice.

**Readback.** metro reads every object back and prints expected vs actual. Any mismatch exits `3`. A green preview is not proof; the readback is.

## What one change looks like

```bash
metro mode write
metro ledger-adjustment preflight --amount=500 --reason="Service credit" \
  --ingest-alias=acme-corp --contract-id=00000000-0000-4000-8000-000000000002 \
  --sandbox --out=ledger.json
metro ledger-adjustment apply --file ledger.json --sandbox --confirm-hash sha256:...      # dry run
metro ledger-adjustment apply --file ledger.json --sandbox --confirm-hash sha256:... \
  --apply --confirm-live-apply=I_UNDERSTAND_THIS_WILL_WRITE_LIVE_METRONOME_SANDBOX
```

The full walkthrough is in [Credits and commits](/docs/guides/credits-and-commits).

## Exit codes

| Code | Meaning | What to do |
|---|---|---|
| `0` | Success | Report the readback. |
| `1` | Validation failure, blocked plan, missing setup or API error | Fix the input, preflight again. |
| `2` | Safety refusal | Stop. Read the refusal code. Don't work around it. |
| `3` | Readback mismatch | The write was accepted but the object differs. Read it fresh before doing anything else. |

## Where to go next

  - [Install](https://metrocli.com/docs/install/): Two commands, then metro doctor.
  - [Keys: metro init](https://metrocli.com/docs/keys/): Create ~/.metro/.env and add a sandbox key.
  - [Copy-paste setup](https://metrocli.com/docs/agents/copy-paste-setup/): Hand the whole setup to your agent in one line.
  - [Safety contract](https://metrocli.com/docs/agents/safety-contract/): Modes, refusals, confirm tokens and readback.