> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle and observability

> Start, stop, restart. Status, logs, and the live TUI dashboard.

Start, stop, restart. Status, logs, and the live TUI dashboard.

## Shortest commands

```bash theme={"system"}
mxnode start --all          # bring everything up
mxnode status               # one-shot per-node health snapshot
mxnode logs --node 0 -f     # tail node-0 logs
```

Every lifecycle command takes the same selector grammar so muscle memory transfers.

## Selectors

| Selector                       | Meaning                                                  |
| ------------------------------ | -------------------------------------------------------- |
| `--all`                        | Every node in `state.toml` (and the proxy, if installed) |
| `--node N`                     | Just node N. Repeat for multiple: `--node 0 --node 2`    |
| `--shard <0\|1\|2\|metachain>` | Every node assigned to that shard                        |
| `--validators-only`            | All validator-role nodes                                 |
| `--observers-only`             | All observer- and multikey-role nodes                    |
| `--select '<expr>'`            | Free-form: `role=validator AND shard=0`                  |

Selectors are **mutually exclusive** — clap rejects more than one at parse time.

## Start / stop / restart

```bash theme={"system"}
mxnode start --all
mxnode stop --node 1
mxnode restart --shard 0
```

`start` maps to `systemctl enable --now <unit>`, `stop` to `systemctl stop`, `restart` to a stop+start cycle.

### Restart strategy

| Flag                           | Default   | Effect                                                                                     |
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------ |
| `--strategy rolling\|parallel` | `rolling` | Rolling: one at a time, wait for `is-active`. Parallel: up to `--max-parallel` concurrent. |
| `--max-parallel N`             | `1`       | Cap when `--strategy parallel`.                                                            |

```bash theme={"system"}
# Rolling (default)
mxnode restart --all

# Parallel up to 2
mxnode restart --all --strategy parallel --max-parallel 2
```

## Status

```bash theme={"system"}
mxnode status
```

```
mxnode 0.8.1 │ mainnet │ 4 nodes │ tags: config v1.11.5.0 binary v1.11.5
H │ idx │ unit                    │ shard      │ nonce      │ pubkey       │ port
──┼─────┼─────────────────────────┼────────────┼────────────┼──────────────┼──────
✓ │ 0   │ elrond-node-0.service   │ 0          │ 21345678   │ erd1...      │ 8080
✓ │ 1   │ elrond-node-1.service   │ 1          │ 21345679   │ erd1...      │ 8081
✗ │ 2   │ elrond-node-2.service   │ 2          │ -          │ -            │ 8082
✓ │ 3   │ elrond-node-3.service   │ metachain  │ 21345670   │ erd1...      │ 8083

health: 3 ok, 0 lagging, 1 failed, 0 unknown
```

### Options

| Flag                   | Default | Effect                           |
| ---------------------- | ------- | -------------------------------- |
| `--watch`              | off     | Repaint until Ctrl+C.            |
| `--interval <SECS>`    | `5`     | Refresh interval with `--watch`. |
| `--format table\|json` | `table` | Output shape.                    |

```bash theme={"system"}
mxnode status --watch --interval 3
mxnode --json status
```

## Logs

```bash theme={"system"}
mxnode logs --node 0 --follow
```

### Options

| Flag             | Default  | Effect                                                               |
| ---------------- | -------- | -------------------------------------------------------------------- |
| `--node N`       | required | Node index. Repeatable for combined stream.                          |
| `--follow`       | off      | Tail new lines. Conflicts with `--save-archive`.                     |
| `--since <SPEC>` | none     | Anything `journalctl --since` accepts (`1h`, `30min`, `2024-01-01`). |
| `--save-archive` | off      | Tarball logs from every node into `<custom_home>/mx-chain-logs/`.    |

```bash theme={"system"}
# Last hour, no follow
mxnode logs --node 0 --since 1h

# Combined tail of two nodes
mxnode logs --node 0 --node 1 --follow

# Archive everything
mxnode logs --save-archive
```

## Dashboard

```bash theme={"system"}
mxnode dashboard
```

Live TUI (built on `ratatui`). Press `q` to quit.

### Options

| Flag              | Default     | Effect                                                                   |
| ----------------- | ----------- | ------------------------------------------------------------------------ |
| `--node N`        | all         | Limit to a subset (repeatable).                                          |
| `--interval <ms>` | `1000`      | REST poll cadence per node.                                              |
| `--host <H>`      | `127.0.0.1` | Override the host the dashboard talks to.                                |
| `--ws-logs`       | off         | Stream logs via the node's `/log` WebSocket instead of tailing the file. |

## Metrics

```bash theme={"system"}
mxnode metrics --port 9090
```

Prometheus scrape endpoint with per-node nonce, lag, and active state. Add it to your scrape config:

```yaml theme={"system"}
scrape_configs:
  - job_name: mxnode
    static_configs:
      - targets: ["host.example.com:9090"]
```

The metrics server runs in the foreground until Ctrl+C. Wrap it in your own systemd unit for production use.

## What gets recorded

| Action                  | Recorded where                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| Every state-changing op | `~/.local/state/mxnode/state.toml`                                                        |
| In-flight upgrades      | `~/.local/state/mxnode/inflight.toml` (cleared on completion or auto-cleared on next run) |
| Migration audit log     | `state.toml` `migrations.entries[]`                                                       |