npm package: @matelink/cli
Description: Relay-first CLI for pairing and bridging OpenClaw gateway traffic
Latest version: 2026.4.34

# @matelink/cli

Relay-first standalone CLI for pairing a mobile client with an OpenClaw host and
keeping a relay bridge online.

## 1) Install

```bash
npm i -g @matelink/cli
```

CLI commands:

```bash
matelink setup
matelink pair
matelink pair 123456
matelink pair --code 123456
matelink bridge
matelink pair-url
matelink status
matelink service status|install|uninstall|restart
```

Recommended first-run flow:

```bash
# 1) prepare OpenClaw config + permissions
matelink setup --relay http://<relay-host>:8090 --public-base http://<gateway-public-host>:<port>

# 2) pair and keep relay bridge online
matelink pair 123456
```

## 2) Testing

Requires Node.js >= 22.

```bash
# run all tests
node --test test/cli.test.mjs

# or via npm
npm test
```

### Test coverage (21 cases)

| Group | Cases | What it verifies |
|-------|-------|-----------------|
| CLI basics | 4 | `--help`, `version`, unknown command, syntax check |
| PATH separator | 1 | `:` vs `;` per platform, deduplication |
| OpenClaw home | 3 | `OPENCLAW_HOME` env, `HOME=/`, empty HOME |
| XML escape | 1 | `&`, `<`, `>` in plist paths |
| systemd escape | 1 | space -> literal `\x20` |
| Command quoting | 2 | `commandToString`, `quoteWindowsCommandArg` |
| PID detection | 1 | own PID, invalid/negative/NaN |
| Lock file | 2 | exclusive create, 48h stale timeout |
| PowerShell encoding | 2 | Base64 roundtrip, CJK paths |
| Service status | 1 | JSON output, platform manager |
| Node version | 1 | source contains >= 16 guard |
| Platform paths | 2 | `.sh` vs `.cmd`, `which` vs `where` |

### CI

- **GitLab CI** (`.gitlab-ci.yml`): Node 22 on Alpine Linux
- **GitHub Actions** (`.github/workflows/test.yml`): Ubuntu/macOS/Windows x Node 22

### Platform compatibility

| Platform | Status |
|----------|--------|
| macOS (launchd) | Fully supported |
| Linux + systemd | Fully supported |
| Linux without systemd (Alpine/OpenRC) | Manual `matelink bridge` only, service install gives friendly error |
| Windows (Task Scheduler) | Supported, tested via CI |

## 3) Configure

```bash
matelink setup --relay http://<relay-host>:8090 --public-base https://gw.example.com
```

This prepares the local OpenClaw gateway for `/v1/responses`, stores relay
credentials in `~/.openclaw/testnextim.state.json`.

## 4) Pairing flow

Start OpenClaw first, then pair from the app:

```bash
openclaw gateway run --bind loopback --port <gateway.port> --force
matelink pair 123456
```

## 5) Service management

```bash
matelink service status      # check status
matelink service install     # install + start background bridge
matelink service uninstall   # stop + remove
matelink service restart     # restart
```

Log locations: `~/.openclaw/matelink/logs/`

```bash
tail -f ~/.openclaw/matelink/logs/bridge.stdout.log
tail -f ~/.openclaw/matelink/logs/bridge.stderr.log
```

## 6) Environment variables

| Variable | Description |
|----------|-------------|
| `OPENCLAW_HOME` | Override OpenClaw home directory (default `~/.openclaw`) |
| `TESTNEXTIM_RELAY_URL` | Override relay base URL |
| `TESTNEXTIM_RELAY_TOKEN` | Bearer token for relay endpoints |
| `OPENCLAW_TESTNEXTIM_GATEWAY_BASE_URL` | Local gateway base URL |
| `OPENCLAW_GATEWAY_PORT` / `OPENCLAW_GATEWAY_HOST` | Explicit gateway host/port |

## 7) Relay architecture

- **Direct mode**: app calls gateway bind URL directly
- **Relay bridge mode** (`matelink bridge`): chat traffic goes through relay, CLI forwards to local gateway
- **Service mode** (`matelink service install`): bridge runs as background service (launchd/systemd/Task Scheduler)