Syncing Configuration

The sync-config command downloads the latest configuration package from the control plane and updates local files. This is useful when network settings change (firewall rules, lighthouse addresses, etc.) without needing to re-register the node.

Basic Usage

# Auto-discovers org if only one is installed
cvpn-manager sync-config

# Specify the organization explicitly
cvpn-manager sync-config --org-slug my-org

By default, both config.yml and the server-issued certificates are updated (--overwrite-certs defaults to true). To keep your existing local certificates and refresh only config.yml, pass --preserve-certs.

Credential Auto-Discovery

sync-config automatically loads credentials from the organization directory. You typically don’t need to pass --api-base, --node-id, or --access-token:

1. If only one organization is installed, --org-slug is auto-discovered
2. --api-base and --node-id are read from credentials.json
3. The API token is loaded from the OS keyring, falling back to credentials.json

Certificates

Certificate handling is controlled by two flags:

• --overwrite-certs (default true) — replaces ca.crt, node.crt, and node.key from the server package in addition to config.yml. Because this is the default, a plain sync-config already refreshes certificates (useful after a renewal on the control plane).
• --preserve-certs (default false) — keeps your existing local certificates and updates only config.yml. This overrides --overwrite-certs.

# Default: updates config.yml AND certificates
cvpn-manager sync-config

# Config-only sync: keep local certificates
cvpn-manager sync-config --preserve-certs

Setting the Nebula Port

The --set-port and --auto-port flags update the node’s external port on the control plane before downloading the new configuration.

Caution

These flags call PATCH /api/org/{slug}/nodes/{id}/ which requires a user/admin JWT, not a node API token. Pass --access-token with a user JWT when using either flag.

# Set a specific port
cvpn-manager sync-config --set-port 4243 --access-token YOUR_JWT

# Auto-detect a free port (scans from 4242 or --set-port upward)
cvpn-manager sync-config --auto-port --access-token YOUR_JWT

# Auto-detect starting from a specific port
cvpn-manager sync-config --auto-port --set-port 5000 --access-token YOUR_JWT

Auth Enforcement

The --enforce flag runs check-auth before syncing. If the node’s credentials have been revoked, the Nebula service is stopped and the sync is skipped:

cvpn-manager sync-config --enforce

This is useful in automated pipelines where you want to ensure the node is still authorized before applying configuration changes.

Live Reload

After updating config.yml, the CLI automatically restarts Nebula so the new configuration takes effect:

• Server mode — runs systemctl restart catalyst-networks-{org}.service
• Desktop mode — sends a restart command to the daemon via the IPC socket

The install mode is determined from node-config.json in the organization directory.

All Flags

Flag	Default	Description
--org-slug	Auto-discovered	Organization slug
--api-base	From credentials.json	Control plane API URL
--node-id	From credentials.json	Node ID
--access-token	From keyring/credentials	API token (user JWT needed for --set-port/--auto-port)
--overwrite-certs	true	Update certificates from the server package (already the default)
--preserve-certs	false	Only update config.yml; keep existing local certificates (overrides --overwrite-certs)
--set-port	—	Set the node’s external port on the server before syncing
--auto-port	false	Find a free UDP port and set it on the server before syncing
--enforce	false	Run check-auth first; skip sync if credentials are revoked

Examples

# Simple sync for a single-org machine
cvpn-manager sync-config

# Config-only sync: keep local certificates
cvpn-manager sync-config --org-slug production --preserve-certs

# Sync with auth enforcement (cron/timer use case)
cvpn-manager sync-config --enforce --verbose

# Change the Nebula port and sync (requires user JWT)
cvpn-manager sync-config --auto-port --access-token $JWT --verbose

Next Steps

• Maintenance commands — credential checks, heartbeats, Nebula management
• Daemon mode — IPC protocol for desktop integration