# Install

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

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

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

**git**

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

**npm**

npm publishing is coming with the first release. Until then, use the git tab. Once it's out, this replaces the first two lines:

```bash
npm install -g @metrocli/metro
metro init
```

**Agent**

Give your agent this line. It installs metro and runs `metro init --agent` for you.

```text
set up metro - https://metrocli.com/llms.txt
```

See [Copy-paste setup](/docs/agents/copy-paste-setup) for what it does, step by step.

## 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.

```text
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:

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

## Troubleshooting

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

## Next

  - [Keys: metro init](https://metrocli.com/docs/keys/): Create your key file and add a sandbox key.
  - [First sandbox read](https://metrocli.com/docs/first-sandbox-read/): Your first read-only call against sandbox.