Keys: metro init
Create ~/.metro/.env, add a sandbox key first, and an optional production key.
metro init sets up your keys. It creates one private file, asks for a sandbox key, checks it with one read-only call, and leaves metro read-only.
Keys never pass through chat or your shell history. You paste them into a hidden prompt, or into the file in your editor.
Where to get a key
You create Metronome API tokens in the Metronome app. Start with sandbox: it can't touch real billing.
| Tenant | Token page | Variable in ~/.metro/.env |
|---|---|---|
| Sandbox | app.metronome.com/sandbox/developer/api-tokens | METRONOME_SANDBOX_KEY |
| Production (optional) | app.metronome.com/developer/api-tokens | METRONOME_PROD_KEY |
Sandbox and production both call https://api.metronome.com. The key decides the tenant, so they must be separate tokens.
Three ways to run it
In an interactive terminal, metro init walks four steps. The tenant summary on the "Connected" line shows your own counts.
$ metro init
metro · Metronome in your terminal
Step 1 of 4 Create your key file
✓ Created ~/.metro/.env (private: only your user can read it)
Step 2 of 4 Add your sandbox key (start here, it can't touch real billing)
1. Open https://app.metronome.com/sandbox/developer/api-tokens
2. Click "Create token", name it "metro", copy it.
3. Paste it here (input is hidden), or press Enter to paste it into the file yourself:
›
✓ Sandbox key saved to ~/.metro/.env as METRONOME_SANDBOX_KEY
… Checking it with a read-only call
✓ Connected to your Metronome sandbox · <n> customers · <n> rate cards
Step 3 of 4 Production key (optional, you can add it later)
Only add this when you're ready for metro to read real billing.
Writes to production still need write mode plus a typed confirmation for every change.
Create one at https://app.metronome.com/developer/api-tokens
Add a production key now? (y/N) › n
· Skipped. Add it any time: metro init --prod
Step 4 of 4 Safety mode
✓ metro is in read-only mode. It can look, preview and validate, but not change anything.
When you want changes applied: metro mode write
You're set. Try:
metro status what metro can see
metro catalog bind --sandbox learn your products and rate cards
metro ops who "Acme" --sandbox find a customer
Using an agent? Tell it: "read ~/.metro/AGENTS.md and run metro status"Add --plain for no colour and ASCII glyphs. Add the production key later with metro init --prod.
The file metro writes
~/.metro/.env is created with mode 0600 inside ~/.metro (mode 0700). It lives outside every repo, so it can't be committed. metro never overwrites a value in it, and re-asserts mode 600 on every run.
# metro keys: this file is private to your user (chmod 600). Never commit or share it.
#
# 1) Sandbox key: start here, it can't affect real billing.
# Create one: https://app.metronome.com/sandbox/developer/api-tokens
METRONOME_SANDBOX_KEY=
#
# 2) Production key: optional. metro is read-only until you run `metro mode write`,
# and every production write still needs a typed confirmation.
# Create one: https://app.metronome.com/developer/api-tokens
METRONOME_PROD_KEY=metro init also writes ~/.metro/AGENTS.md (the agent manual, replaced on every run) and ~/.metro/mode.json (read-only, only if no mode is set yet).
Never paste a key into chat
Not to an agent, not in an issue, not in a commit. If it happens, revoke the token in Metronome and create a new one. metro prints key fingerprints, never values.
How the check works
metro makes one read-only call per key: GET /v1/customers?limit=100. When the key works, a second read-only call, POST /v1/contract-pricing/rate-cards/list?limit=100, fills in the tenant summary. The key only ever goes in the Authorization header and is never logged.
Troubleshooting
These are the exact messages metro prints, and what to do.
| Message | Cause | Fix |
|---|---|---|
Metronome rejected the sandbox key. It may be revoked or copied with a missing character. Create a new one at <url> and replace the line in ~/.metro/.env. | HTTP 401 or 403 | Create a new token, replace the line, run metro init --check. |
Couldn't reach api.metronome.com. Check your connection or proxy, then run metro init --check. | No network, or a proxy blocks it | Fix the connection, then check again. |
Your sandbox and production keys are the same. Sandbox and production need separate tokens. | Both lines hold one value | Create a sandbox token and put it on the METRONOME_SANDBOX_KEY= line. |
Metronome answered HTTP <status> to the sandbox key check. Try again in a minute: metro init --check | Any other HTTP error | Wait, then check again. |
Could not make ~/.metro/.env private (mode is ..., expected 600). Run: chmod 600 ~/.metro/.env | The filesystem refused chmod | Run the printed chmod. |
Not saved (already-set) | The key line already has a value | metro never overwrites. Edit the line yourself. |
Press Ctrl+C at any prompt and metro stops with Stopped. Nothing else changed. Run metro init again any time.
Next
Run your first sandbox read.