Maintenance Commands

check-auth

Verifies that the node’s credentials are still valid with the control plane. If credentials have been revoked, the Nebula service is stopped and a breadcrumb file is written to prevent further attempts.

# Check a single organization
cvpn-manager check-auth --org-slug my-org

# Check all installed organizations
cvpn-manager check-auth --all

One of --org-slug or --all is required.

How It Works

For each organization:

Checks for an existing auth-revoked.json breadcrumb — if present, skips (credentials already known revoked)
Loads credentials from credentials.json and the OS keyring
Calls POST /api/org/{slug}/nodes/{id}/checkin/ to test the token
Handles the response:
- 2xx — credentials are valid, no action taken
- 401 / 403 / 404 — credentials are revoked: stops the systemd unit and writes auth-revoked.json
- 5xx / network error — transient failure: logs a warning, leaves the service running

When credentials are revoked, the CLI writes auth-revoked.json to the organization directory:

{
  "revoked_at": "2025-01-15T10:30:00Z",
  "reason": "401 Unauthorized",
  "node_id": 42
}

Once this file exists, check-auth skips the organization entirely without hitting the API. To re-enable, delete the file and re-register the node.

Auth Timer (Server Mode)

In server mode, registration creates a systemd timer that runs check-auth --all every 60 seconds (plus 30 seconds after boot):

Service: catalyst-networks-auth.service
Timer: catalyst-networks-auth.timer

This ensures that revoked nodes are stopped promptly without manual intervention.

checkin

Sends a heartbeat to the control plane with the node’s current version and uptime.

# Check in all installed organizations
cvpn-manager checkin

# Check in a specific organization
cvpn-manager checkin --org-slug my-org

The heartbeat payload:

{
  "version": "1.0.0",
  "uptime": 86400
}

Without --org-slug, the CLI discovers all installed organizations by scanning for directories containing credentials.json.

In daemon mode, checkin runs automatically every 60 seconds for all provisioned teams.

Nebula Management

The nebula command group manages the Nebula binary independently of node registration.

nebula check

Reports whether Nebula is installed and its version:

cvpn-manager nebula check

Output:

Nebula: /usr/local/bin/nebula
Version: 1.9.5

nebula install

Downloads and installs the latest Nebula release from GitHub:

cvpn-manager nebula install

If Nebula is already installed, the command prints its location and suggests using nebula update instead.

Use --dir to specify a custom installation directory:

cvpn-manager nebula install --dir /opt/nebula/bin

nebula update

Updates an existing Nebula installation to the latest version:

cvpn-manager nebula update

The update uses atomic file replacement (write to .tmp, then rename) so it is safe to run while Nebula is active — the running process keeps its file handle on the old binary, and the next restart picks up the new one.

check-port

Checks whether UDP ports are available for Nebula to bind:

# Check a single port
cvpn-manager check-port --start 4242

# Check a range of ports
cvpn-manager check-port --start 4242 --end 4250

Output shows each port’s status:

free:4242
in_use:4243
free:4244

Both --start and --end default to 4242. With no flags, only port 4242 is checked. Supply --end to scan a range; if --end is lower than --start, it is clamped up to --start (single-port check).

install-systemd

Recreates the systemd unit file for an organization. Useful after changing install modes or if the unit file was deleted.

cvpn-manager install-systemd --org-slug my-org

Flag	Default	Description
`--org-slug`	—	Organization slug (required)
`--config-path`	Auto-detected	Path to `config.yml`
`--mode`	From `node-config.json`	Install mode: `server` or `desktop`

The mode is resolved in this order:

--mode flag
$CATALYST_INSTALL_MODE environment variable
install_mode field in node-config.json
Falls back to desktop

After writing the unit file, the command runs systemctl daemon-reload and systemctl enable --now to activate it.

install-launchd

Recreates the launchd plist for an organization on macOS:

cvpn-manager install-launchd --org-slug my-org

version

Prints the current version and checks for updates:

cvpn-manager version