Install

Install metro with git clone and install-global.sh, then check it with metro doctor.

View .md

metro needs Node 18 or newer, git and npm. It runs on macOS and Linux.

git clone --depth 1 https://github.com/metrocli/metro.git ~/.metro/src
bash ~/.metro/src/scripts/install-global.sh
metro init

What install-global.sh does

The script keeps a persistent checkout at ~/.metro/src and links it, so metro is a real file on your PATH.

  1. Clears any broken global @metrocli/metro link.
  2. Clones ~/.metro/src, or pulls with --ff-only if it already exists. It never deletes the checkout.
  3. Runs npm install and npm link inside it.
  4. Proves metro is on PATH, and refuses to finish if npm linked into its temp cache.

Run it again any time to update: bash ~/.metro/src/scripts/install-global.sh. Set METRO_INSTALL_DIR to use another checkout path.

Don't use npm install -g git+https://...

On current npm that often leaves a metro symlink into an empty temp checkout. You see "added 1 package", then metro: command not found. The script exists to avoid exactly this.

Check the install: metro doctor

metro doctor checks the install without touching Metronome. Add --json for agents. The output below is illustrative of a healthy install; your paths differ.

metro install doctor
Healthy: yes
[pass] Node.js 18+: Node 24.22.2
[pass] metro on PATH: /usr/local/bin/metro
[pass] Global @metrocli/metro link: ...
[info] Source checkout: ~/.metro/src

Each failing check prints a fix: line with the exact command, and doctor ends with Next:. The checks are:

CheckWhat it proves
INSTALL-NODE-001Node 18 or newer
INSTALL-PATH-001metro resolves on your PATH
INSTALL-NPM-002The global @metrocli/metro link exists and isn't a temp-cache link
INSTALL-CHECKOUT-003~/.metro/src is a real git checkout
INSTALL-GH-002A warning only: whether the GitHub CLI is signed in

Troubleshooting

You seeDo this
metro: command not found after installRun export PATH="$(npm prefix -g)/bin:$PATH", then metro doctor.
~/.metro/src exists but is not a git checkoutOpen a new terminal in ~, remove that folder yourself, and run the two git commands again.
ENOTDIR on a retryYou used npm install -g git+... earlier. Run install-global.sh; step 1 clears the broken link.

Next

Keys: metro init

Create your key file and add a sandbox key.

First sandbox read

Your first read-only call against sandbox.

Overview

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

Keys: metro init

Create ~/.metro/.env, add a sandbox key first, and an optional production key.

On this page

What install-global.sh doesCheck the install: metro doctorTroubleshootingNext