# Router

> Status: Alpha – this is under active development and interfaces/behavior are subject to change.

## CLI

CLI install

```bash
pnpm add -g @morpho-dev/router
```

- Router configuration is read from a TOML file
- `router start` accepts `--config-file` (or `ROUTER_CONFIG_FILE`/`./router.toml`)
- Indexer chains can be selected in TOML (`[indexer].chains`) or at runtime with `--chains`
- Seed mock offers with `--mock <n>` for testing
- Load offers from JSON file with `--file <path>`
- When `[indexer]` is enabled, a monitoring server is started (default `:8083`) exposing `/readyz` and `/metrics`
- API `/metrics` is API-only (HTTP/process telemetry)
- Indexer `/metrics` is the source of truth for sync gauges (`router_collector_block_number`, `router_chain_block_number`, `router_chain_remote_block_number`)
- Collector lag is derived in PromQL (`remote - collector`) and is no longer emitted as `router_collector_lag_blocks`

Examples:

```bash
# Start router from a config file
router start --config-file ./router.toml

# Start router using the env fallback
ROUTER_CONFIG_FILE=./router.toml router start

# Start router indexer only on one chain (when [indexer].chains is omitted)
router start --config-file ./router.toml --chains ethereum

# Start router with mock offers for testing
router start --config-file ./router.toml --mock 100

# Start router with offers loaded from file
router start --config-file ./router.toml --file offers.json
```

### Chain

Use `router chain` to manage the anvil chain for dev and E2E workflows.

```bash
# Start a chain and emit JSON status
router chain start --output json

# Check chain status
router chain status --output json

# Stop the chain and purge state
router chain stop --purge
```

Example `router.toml`:

```toml
[logging]
level = "info"

[database]
url_env = "DATABASE_URL"

[api]
port = 7891

[indexer]
block_window = 8000
metrics_port = 8083
# interval = 10000
# interval_by_chain = { base = 500, ethereum = 10000 }
# chains = ["ethereum"]
# If omitted, `router start` indexes all chains defined under [chains]

[chains."ethereum"]
rpc_url_env = "ETHEREUM_RPC_URL"
```

<!-- AUTO-GENERATED: CLI-HELP START -->
### CLI reference

#### Global

```text
Usage: router [options] [command]

Router package for Morpho protocol

Options:
  -V, --version         output the version number
  -h, --help            display help for command

Commands:
  start [options]       Start Router services.
  chain                 Manage the chain lifecycle (Prool server with Anvil).
  gatekeeper [options]  Start Gatekeeper validation service.
  help [command]        display help for command
```

#### start

```text
Usage: router start [options]

Start Router services.

Options:
  --config-file <path>  Path to router TOML config file
  --mock <n>            Number of mock offers to seed
  --chains <names>      Comma-separated chain names to index (e.g.
                        ethereum,base)
  --file <path>         Seed offers from a JSON file
  -h, --help            display help for command
```

#### chain

```text
Usage: router chain [options] [command]

Manage the chain lifecycle (Prool server with Anvil).

Options:
  -h, --help         display help for command

Commands:
  start [options]    Start a Prool server managing an Anvil instance.
  status [options]   Show chain status.
  stop [options]     Stop the chain process.
  restart [options]  Restart the chain process.
  deploy [options]   Deploy contracts to an already-running Anvil instance.
  logs [options]     Read anvil logs.
  help [command]     display help for command
```

#### gatekeeper

```text
Usage: router gatekeeper [options]

Start Gatekeeper validation service.

Options:
  --config-file <path>  Path to router TOML config file
  -h, --help            display help for command
```

<!-- AUTO-GENERATED: CLI-HELP END -->
