reefctl

CLI for managing OpenClaw instances. Keeps local configuration files in sync with the cloud dashboard — edit locally and changes push automatically, edit on the web and reefctl pull brings them down.

Install

npm install -g reefctl

Quick Start

# 1. Register an instance on the web dashboard, then connect it:
reefctl init

# 2. Install the background daemon (systemd user service):
reefctl service install

# 3. That's it — file changes sync automatically.
#    To check status:
reefctl list

How It Works

  Local files              reefctl daemon              Cloud dashboard
 +-----------+          +-----------------+          +----------------+
 | workspace/|  watch   |  chokidar       |  push    |                |
 | configs   | -------> |  file watcher   | -------> |  Convex DB +   |
 |           |          |                 |          |  file storage  |
 |           |  write   |  pull on each   |  pull    |                |
 |           | <------- |  heartbeat      | <------- |  web editor    |
 +-----------+          +-----------------+          +----------------+

The daemon runs as a systemd user service. It watches configured directories with chokidar, pushes changes to the Convex backend via HTTP, and pulls web-edited files on each heartbeat (every 60 seconds).

Commands

reefctl init [name]

Interactive setup for a new instance. Prompts for:

• Convex HTTP Actions URL — your *.convex.site endpoint
• API token — generated from the web dashboard
• Watch directory — local directory to sync (default: ~/.openclaw)
• Include paths — files/directories to watch (default: openclaw.json, workspace/)
• Exclude paths — files/directories to skip

Tests the connection, saves config to ~/.reefctl/config.json, and does an initial push of all existing files.

reefctl init              # creates instance named "default"
reefctl init staging      # creates instance named "staging"

reefctl list

Shows all configured instances with their sync status, URLs, and last sync time. Works even when the daemon is stopped (shows configured instances as "stopped").

reefctl status

Shows daemon uptime, PID, and instance count.

reefctl push [path]

Manually push files to the cloud.

reefctl push                          # push all files for the default instance
reefctl push workspace/config.json    # push a single file
reefctl push -i staging               # push all files for a specific instance

reefctl pull

Pull files that were edited on the web dashboard.

reefctl pull                # pull for the default instance
reefctl pull -i staging     # pull for a specific instance

reefctl service install

Installs and starts reefctl-daemon.service as a systemd user service. The daemon auto-restarts on failure and starts on login.

reefctl service install     # install and start
reefctl service uninstall   # stop and remove

Run loginctl enable-linger to keep the daemon running even when you're not logged in.

reefctl remove <name>

Removes an instance from the local config and reloads the daemon.

Configuration

Config is stored at ~/.reefctl/config.json:

{
  "version": 2,
  "instances": {
    "default": {
      "url": "https://your-app.convex.site",
      "token": "your-api-token",
      "watchDir": "/home/user/.openclaw",
      "includes": ["openclaw.json", "workspace/"],
      "excludes": ["workspace/my-website-repo/"],
      "hooks": {
        "openclaw.json": "openclaw gateway restart"
      }
    }
  }
}

Hooks

Hooks run shell commands when specific files change. Useful for restarting services after config updates.

Excludes

Supports glob patterns:

workspace/reefctl/          # trailing slash — directory prefix match
workspace/*/dist            # * — single segment wildcard
**/convex/_generated        # ** — any depth wildcard

node_modules/ and .git/ are always excluded. Binary files (.exe, .so, .dylib, etc.) and files larger than 50 MB are skipped automatically.

Multi-Instance

Run multiple instances pointing to different backends or watch directories:

reefctl init prod
reefctl init staging
reefctl list                # shows both instances
reefctl push -i staging     # target a specific instance

Requirements

• Node.js >= 18
• Linux with systemd (for the daemon service)

License

MIT