CLI Overview

cvpn-manager is a cross-platform CLI that automates node provisioning and runtime management for Catalyst Networks. It handles registration, certificate provisioning, system service management, credential storage, and optionally runs as a privileged daemon for desktop integration.

Command Reference

Command	Description
register	Register a new node with the control plane
sync-config	Update local config from the control plane
check-auth	Verify credentials are still valid; stop revoked orgs
checkin	Send a heartbeat to the control plane
nebula check	Check if Nebula is installed and report its version
nebula install	Download and install the latest Nebula binary
nebula update	Update Nebula to the latest version
check-port	Check if UDP ports are available
install-systemd	Create or recreate the systemd unit (Linux)
install-launchd	Create or recreate the launchd plist (macOS)
install-tap	Install the wintun network driver (Windows only)
self-update	Download and replace the running binary with the latest published release
version	Print version and check for updates

The CLI can also run as a daemon when started with --ipc-mode, supervising Nebula processes and accepting commands over a Unix socket or Windows named pipe.

Global Flags

These flags are available on every command:

Flag	Default	Description
--verbose, -v	false	Enable debug logging
--log-file	—	Write logs to a file
--dry-run	false	Preview changes without applying
--config-root	Platform-specific	Root directory for team configurations
--ipc-mode	—	Start daemon mode (socket or pipe)
--socket-path	Platform-specific	Unix socket path for daemon IPC
--pipe-name	Platform-specific	Named pipe path for daemon IPC (Windows)
--state-db-path	Platform-specific	Path to the daemon state database (BoltDB)
--autostart	true (Linux)	Auto-start configured teams on daemon boot
--nebula-binary	Platform-specific	Path to the Nebula binary

Platform Defaults

Linux

Path	Default
Config root	/etc/catalyst-networks/
Nebula binary	/usr/local/bin/nebula
IPC socket	/var/run/tech.deltaops.cvpn/cmd.sock
State database	/var/lib/tech.deltaops.cvpn/state.db

macOS

Path	Default
Config root	/etc/catalystvpn/
Nebula binary	/usr/local/bin/nebula
IPC socket	/var/run/tech.deltaops.cvpn/cmd.sock
State database	/var/lib/tech.deltaops.cvpn/state.db

Windows

Path	Default
Config root	C:\ProgramData\Catalyst\networks\
Nebula binary	C:\Program Files\Catalyst\nebula\nebula.exe
IPC pipe	\\.\pipe\tech.deltaops.cvpn.cmd
State database	C:\ProgramData\Catalyst\data\state.db

Files Per Organization

After registration, each organization directory contains:

File	Mode	Description
config.yml	0644	Nebula configuration
ca.crt	0644	Certificate Authority certificate
node.crt	0644	Node certificate
host.crt	0644	Host certificate
node.key	0600	Node private key
host.key	0600	Host private key
credentials.json	0600	API connection details and node token
node-config.json	0644	Node metadata (name, IP, mode, lighthouse status)

Credential Storage

The CLI stores the node’s API token in two locations:

1. OS keyring (primary) — Service name catalyst-manager, account {org-slug}:{node-id}
2. credentials.json (fallback) — Used when the keyring is unavailable (headless servers, containers)

When loading credentials, the keyring value takes precedence over the file-based token.

The credentials.json file contains:

{
  "api_base": "https://app.catalystnetworks.io",
  "org_slug": "my-org",
  "node_id": 42,
  "api_token": "..."
}

Node API Token Scope

The API token returned during registration is scoped to two endpoints only:

• POST /api/org/{slug}/nodes/{id}/checkin/ — heartbeat
• GET /api/org/{slug}/nodes/{id}/download_config/ — fetch config package

All other API endpoints (including GET, PATCH, DELETE on /nodes/{id}/) return 403 Forbidden and require a user/admin JWT passed via --access-token.

Install Modes (Linux)

Linux supports two install modes that determine how Nebula is managed at runtime:

Mode	Systemd runs	Auth timer	Use case
server	nebula directly	Yes (60s interval)	Headless servers, always-on infrastructure
desktop	cvpn-manager daemon	No	Desktop machines with GUI app integration

Set the mode during registration with --mode server or --mode desktop. The default is desktop. See Registering a Node for details.

Next Steps

• Installation — download and install the CLI
• Register a node — connect a machine to your network
• Sync configuration — update config without re-registering
• Daemon mode — run as an IPC daemon for desktop integration
• Maintenance commands — check-auth, checkin, nebula management, and more