@matelink/cli

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

1) Install

npm i -g @matelink/cli

CLI commands:

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:

# 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.

# 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

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:

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

5) Service management

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/

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)