> For the complete documentation index, see [llms.txt](https://docs.astralbeam.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.astralbeam.io/operators/worker-commands.md).

# Worker Commands

Commands for managing bridge relayer workers.

## start

Start relay services.

```bash
bridge-cli start [options]
```

**Options:**

| Option                  | Default | Description                                            |
| ----------------------- | ------- | ------------------------------------------------------ |
| `-d, --direction <dir>` | `both`  | Relay direction: `eth2casper`, `casper2eth`, or `both` |

**Examples:**

```bash
# Start all workers
bridge-cli start

# Start only EVM→Casper worker
bridge-cli start --direction eth2casper

# Start only Casper→EVM worker
bridge-cli start --direction casper2eth
```

**Output:**

```
Starting bridge relayer...

Configuration:
  Direction: both
  Chains: sepolia (11155111), baseSepolia (84532)
  P2P: enabled

[12:00:00] INFO: EVM→Casper worker started
[12:00:01] INFO: Casper→EVM worker started
[12:00:02] INFO: Connected to 4 P2P peers
[12:00:02] INFO: Listening for events...
```

***

## stop

Stop relay services.

```bash
bridge-cli stop [options]
```

**Options:**

| Option                  | Default | Description                                            |
| ----------------------- | ------- | ------------------------------------------------------ |
| `-d, --direction <dir>` | `both`  | Relay direction: `eth2casper`, `casper2eth`, or `both` |

**Examples:**

```bash
# Stop all workers
bridge-cli stop

# Stop only EVM→Casper worker
bridge-cli stop --direction eth2casper
```

***

## status

Show relay service status.

```bash
bridge-cli status
```

**Output:**

```
Bridge Relayer Status
=====================

Processes:
  evm2casper:  Running (PID: 12345)
  casper2eth:  Running (PID: 12346)

Configuration:
  Relayer ID:  0
  Log Level:   info

Contract Addresses:
  Sepolia Locker:  0x6aaea12cF566C9fddbC7082c15d38F1447a57D10
  Base Locker:     0xB4Fcc5E0b3590272820b89aBfc55E8ceb7cFDabc
  TokenFactory:    hash-bf16ba78a7ecfb0e64756aa8468251110f29639f38ccaf9bdb01b6f38a15c2f2
  EthClient:       hash-fa183fe46e92b65da88265deb0d48c7ae44bf44d7917f19875f4457321497aa2
```

***

## watch

Launch the full-screen TUI (Terminal User Interface) dashboard.

```bash
bridge-cli watch [options]
```

**Options:**

| Option                    | Default | Description                 |
| ------------------------- | ------- | --------------------------- |
| `-r, --refresh <seconds>` | `2`     | Refresh interval in seconds |

**Examples:**

```bash
# Launch TUI with default refresh
bridge-cli watch

# Launch with 5-second refresh
bridge-cli watch --refresh 5
```

### TUI Dashboard Layout

The dashboard is a blessed-based terminal UI with multiple panels:

```
┌───────────────────────────────────────────────────────────────────────────────┐
│                      CASPER-EVM BRIDGE RELAYER                                │
├───────────────────────────────────┬───────────────────────────────────────────┤
│ Chain: All Chains         [c]     │ Peers: [0] Local  1  2  3  4        [Tab] │
├──────────────────┬────────────────┴───┬───────────────────────────────────────┤
│ Eth2Casper       │ Casper2Eth         │ System                                │
│                  │                    │                                       │
│ Status: Running  │ Status: Running    │ Uptime: 2d 4h 32m                     │
│ Last Block: 5.1M │ Last Block: 2.0M   │ Memory: 256 MB                        │
│ Finalized: 5.0M  │ Pending: 0         │ Peers: 4/5                            │
│ Pending: 2       │ Burns: 42          │ Relayer: R0 (3-of-5)                  │
│ Locks: 156       │ Unlocks: 38        │ Log Level: info                       │
│ Burns: 12        │                    │                                       │
├──────────────────┴────────────────────┴───────────────────────────────────────┤
│ Signature Collection                                                          │
│  MINT#42: ████████░░ 4/5 (Leader: R2)   UNLOCK#15: ██████████ 5/5 Complete    │
├───────────────────────────────────────────────────────────────────────────────┤
│ Recent Events                                                                 │
│                                                                               │
│ [12:00:15] Lock detected: 100 USDC (Sepolia → Casper)                         │
│ [12:00:45] Signature collected: MINT#42 (4/5)                                 │
│ [12:01:00] Mint submitted: 100 USDC to account-hash-abc...                    │
│ [12:01:30] Burn detected: 50 USDC (Casper → Sepolia)                          │
│                                                                               │
├───────────────────────────────────────────────────────────────────────────────┤
│     Keys: 0=Local, 1-9=Peers, Tab=Cycle | c/C=Chain | 'q' quit, 'h' help      │
└───────────────────────────────────────────────────────────────────────────────┘
```

### Dashboard Panels

| Panel                    | Description                                |
| ------------------------ | ------------------------------------------ |
| **Header**               | Title and current view                     |
| **Chain Selector**       | Switch between chains (press `c` to cycle) |
| **Peer Selector**        | View local or remote peer metrics          |
| **Eth2Casper**           | EVM→Casper worker status and stats         |
| **Casper2Eth**           | Casper→EVM worker status and stats         |
| **System**               | Memory, uptime, peer count, relayer info   |
| **Signature Collection** | In-progress multi-sig collection status    |
| **Events**               | Scrollable log of recent bridge events     |
| **Footer**               | Keyboard shortcuts reference               |

### Keyboard Shortcuts

| Key                  | Action                      |
| -------------------- | --------------------------- |
| `0`                  | Switch to local view        |
| `1-9`                | Switch to peer 1-9          |
| `Tab`                | Cycle to next peer          |
| `Shift+Tab`          | Cycle to previous peer      |
| `c`                  | Cycle to next EVM chain     |
| `C` (Shift+c)        | Cycle to previous EVM chain |
| `h` or `?`           | Show help dialog            |
| `q`, `Esc`, `Ctrl+C` | Quit dashboard              |

### Peer Switching

The TUI supports viewing metrics from other relayer nodes in the P2P network:

* **Local (0)**: Your own relayer's metrics
* **Peers (1-9)**: Remote peer metrics fetched via HTTP/HTTPS

When viewing a peer, the dashboard fetches their Prometheus metrics endpoint and displays their worker status, signature collection progress, and event logs.

***

## Service Commands

Manage bridge as a systemd service.

### service install

Install bridge as a systemd service.

```bash
bridge-cli service install [options]
```

**Options:**

| Option            | Default  | Description        |
| ----------------- | -------- | ------------------ |
| `--user <user>`   | `bridge` | Service user       |
| `--config <path>` | -        | Configuration file |

Creates `/etc/systemd/system/bridge-relayer.service`.

***

### service uninstall

Remove systemd service.

```bash
bridge-cli service uninstall
```

***

### service start

Start the systemd service.

```bash
bridge-cli service start
```

Equivalent to: `sudo systemctl start bridge-relayer`

***

### service stop

Stop the systemd service.

```bash
bridge-cli service stop
```

***

### service restart

Restart the systemd service.

```bash
bridge-cli service restart
```

***

### service status

Show service status.

```bash
bridge-cli service status
```

***

### service logs

View service logs.

```bash
bridge-cli service logs [options]
```

**Options:**

| Option           | Default | Description             |
| ---------------- | ------- | ----------------------- |
| `--follow`       | `false` | Follow log output       |
| `--lines <n>`    | `100`   | Number of lines to show |
| `--since <time>` | -       | Show logs since time    |

**Examples:**

```bash
# View last 100 lines
bridge-cli service logs

# Follow logs
bridge-cli service logs --follow

# View logs from last hour
bridge-cli service logs --since "1 hour ago"
```

Equivalent to: `journalctl -u bridge-relayer`

***

## Process Management

Production deployments use **systemd** for process management. The Ansible playbooks automatically configure the systemd service.

### Manual systemd Commands

```bash
# Check status
sudo systemctl status bridge-relayer

# Start service
sudo systemctl start bridge-relayer

# Stop service
sudo systemctl stop bridge-relayer

# Restart service
sudo systemctl restart bridge-relayer

# View logs
sudo journalctl -u bridge-relayer -f

# Enable on boot
sudo systemctl enable bridge-relayer
```

### Service Configuration

The systemd service file is deployed to `/etc/systemd/system/bridge-relayer.service`:

```ini
[Unit]
Description=AstralBeam Relayer
After=network.target

[Service]
Type=simple
User=bridge
WorkingDirectory=/opt/bridge
ExecStart=/usr/local/bin/bridge-cli start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

***

## Health Checks

### Metrics Endpoint

The relayer exposes Prometheus metrics on port 9090 (configurable):

```bash
curl http://localhost:9090/metrics
```

### Manual Health Check

```bash
bridge-cli status
```

Verify all workers show "Running" status.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.astralbeam.io/operators/worker-commands.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.