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

# cowboy cluster top

> Live terminal view of a Cowboy cluster, one box per system

## Synopsis

```bash theme={null}
cowboy cluster top [--rpc-url <url>] [--statusz <url>]... [--interval-ms <ms>]
```

The live view is a subcommand of `cowboy cluster`; there is no top-level `cowboy top`.

## Behavior

1. Resolve the RPC URL via [auto-discovery](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md) unless `--rpc-url` is given.
2. Enter the terminal's alternate screen in raw mode and poll two kinds of source on every interval:
   * **Chain view** (always): the node's public read surface — `/health/ready`, `/ras/stats`, `/runners/active`, `/cbss/proxies`, and `/statusz/targets` — what the chain believes about the cluster.
   * **`/statusz` self-reports** (when reachable): each daemon's standardized status report. Every `--statusz <url>` is polled; a report self-identifies through its `system` field, so relays, cbssd, cbqsd, runners, and indexers all use the one flag. An unreachable report is rendered as a state, not raised as an error.
3. Render one box per system (node, indexer, cbfs, cbss, cbqs, runners) with health color and live activity.
4. Restore the terminal on exit, on error, or on panic.

**Keys:**

| Key | Action |
| - | - |
| `q`, `Ctrl-C`, `Esc` (grid) | Quit |
| Arrow keys or `h`/`j`/`k`/`l` | Move the cursor between boxes |
| `Enter` | Drill into the selected system |
| `Up`/`Down`, `Home`/`End` (runners detail) | Scroll the runner list |
| `Esc`, `Backspace`, `Enter` (detail) | Return to the grid |

## Flags

| Flag | Default | Description |
| - | - | - |
| `--rpc-url` | Auto-discovered | Node RPC URL |
| `--statusz` | None (repeatable) | Daemon `/statusz` base URL |
| `--interval-ms` | `2000` | Poll interval in milliseconds |

## Example

```bash theme={null}
$ cowboy cluster top --statusz http://relay-1:9001 --statusz http://runner-1:9002
```

The command is interactive and takes over the terminal; there is no non-interactive output mode.

## Edge Cases

* `cowboy cluster top` is read-only and needs no private key.
* A `--statusz` URL must be an `http://` or `https://` origin with no path, query, fragment, or embedded credentials, at most 256 characters; anything else is rejected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.