CLI

One binary is the daemon and its CLI:

cerberd <command> [flags]

Flags may come before or after positional arguments. cerberd help prints the built-in summary.

Picking an instance

Setup commands (init, import, down, db backup, run) take the instance as an argument: an interface name (wg0 → /etc/cerberd/wg0.yaml) or a config path whose base name is the interface (/tmp/wg0.yaml → wg0), like wg-quick.

Every other command talks to a running daemon over its unix socket:

Flag	Meaning
-i <interface>	the instance’s socket, /run/cerberd/<interface>.sock
--socket <path>	a socket path directly (overrides -i); default $CERBERD_SOCKET

Without either, the CLI uses the only socket in /run/cerberd, and asks for -i when there are several. status and events also take the interface as a positional argument.

The socket is 0660 in a 0750 directory owned by cerberd: run the CLI as root or as a member of the cerberd group.

Exit codes

Code	Meaning
0	success
1	the command failed, including bad flags or arguments (message on stderr: cerberd <command>: ...)
2	no command, unknown command, or -h/--help on a command
78	setup error in cerberd run: config, database, hub key. systemd doesn’t restart it

Setup

Run on the hub as root.

init

cerberd init <interface | config-file> [--private-key-file F]

Creates the database (hub.db, default /var/lib/cerberd/<interface>.db) with a new hub key, or the one in F. Prints the hub’s public key. Refuses to overwrite an existing database. The config must exist.

import

cerberd import <interface | config-file> [--wgdashboard DB] [--conf FILE] [--skip X]...
               [--dry-run] [--json] [--db FILE] [--write-config] [--offline]

Creates the database from the live interface, its wg-quick config and optionally WGDashboard. See Migration.

Flag	Meaning
--wgdashboard DB	WGDashboard SQLite database, e.g. /opt/WGDashboard/src/db/wgdashboard.db
--conf FILE	wg-quick config; default /etc/wireguard/<interface>.conf when it exists
--skip X	leave a peer out: public key, WGDashboard name or IP. Repeatable
--dry-run	print the report, write nothing
--json	the report as JSON on stdout (notes go to stderr)
--db FILE	database to create; default hub.db. Must match hub.db if the config exists
--write-config	write the derived config when /etc/cerberd/<interface>.yaml doesn’t exist
--offline	don’t read the live interface: peers and hub key from --conf (a test run away from the hub)

Problems in the report stop the import (N problems: nothing written).

down

cerberd down <interface> [--force]

Deletes the interface. It refuses while the daemon answers on its socket, since the daemon would bring it back; stop it first, or pass --force.

db backup

cerberd db backup <interface | config-file> <file>

A consistent copy of the database, safe while the daemon runs. The file holds private keys; it is created 0600 and never overwritten. See Backup and restore.

Daemon

run

cerberd run <interface | config-file> [--debug]

Runs the daemon in the foreground, logging to stderr. systemd runs cerberd run %i from cerberd@.service. --debug enables debug logging.

Peers

All peer commands accept --json to print the API response instead of a table. A <name> may also be a peer’s overlay address or full public key.

peer ls

cerberd peer ls [--tag T] [--blocked | --active] [--json]

Lists peers with tags, state (online, offline, blocked, not on hub), endpoint, router binding and label.

peer show

cerberd peer show <name>

One peer as JSON, including its hub state (handshake, rx/tx). Never shows private keys.

peer add

cerberd peer add <name> --ip IP [--ip IP]... [--public-key K | --private-key-file F]
                 [--label L] [--tag T]... [--routeros] [--router-url URL]

Flag	Meaning
--ip	overlay /32 or LAN /24. Repeatable, at least one overlay
--public-key K	the spoke’s public key; it keeps its private key
--private-key-file F	the spoke’s private key. Without either key flag cerberd generates one
--label L	free-text display name
--tag T	tag. Repeatable
--routeros	the peer is a RouterOS router cerberd may drive (routeros.defaults)
--router-url URL	RouterOS REST URL; implies --routeros

peer set

cerberd peer set <name> [--name N] [--ip IP]... [--label L] [--routeros | --no-routeros]
                 [--router-url URL] [--keepalive S]

Only the given flags change. --ip replaces all IPs. --keepalive is the hub-side persistent keepalive in seconds. --no-routeros removes the router binding. Other fields (notes, preshared key, endpoint, client overrides) are API-only: PATCH /v1/peers/{name}.

peer block / peer unblock

cerberd peer block [--force] <name>
cerberd peer unblock <name>

Block takes the peer’s direct links down, then removes it and its routes from wg0, keeping the record, keys and addresses. If a router can’t be reached to take a link down it stops, unless --force.

peer rm

cerberd peer rm [--force] <name>

Like block, then deletes the record, keys and reservations.

peer rotate

cerberd peer rotate <name> [--public-key K]

Gives the peer a new key pair (generated, or only the public key K). The old key leaves wg0.

peer config

cerberd peer config <name> [--format wg-quick|routeros]

Prints the spoke’s config: a wg-quick file (default) or an idempotent RouterOS script.

conflicts

cerberd conflicts <range>...
cerberd conflicts --ip IP [--ip IP]... [--name N]

The first form lists the peers whose addresses overlap each range, blocked ones included. The second is a dry run of creating a peer: it prints ok: no conflicts, or every problem and clash and exits 1.

overlay free

cerberd overlay free <range>

Prints the lowest free overlay address in the range (10.99.23.31/32), skipping its first and last address. It isn’t reserved.

Links and status

status

cerberd status [interface] [--json]

The hub (peers on the interface, known, blocked, foreign, daemon version, last reconcile error, guard), every node (overlay, key, online, endpoint, tags, prefixes, router state, tagged objects) and every link. Routers of offline nodes aren’t checked. It warns when the daemon runs a different version than this binary.

events

cerberd events [interface] [--follow] [--json]

Recent events (the last 1000); --follow keeps streaming new ones, --json prints NDJSON. See Events.

link up

cerberd link up <a> <b> [--force] [--json]

Builds a direct link between two nodes (name, overlay IP or a public key prefix of at least 4 characters) and prints how it ended. Exits 1 unless the link is active. --force keeps it even if it isn’t faster than the hub. See Direct links.

link down

cerberd link down <a> <b>

Removes the direct link; traffic falls back to the hub.

version

cerberd version        # also --version, -V
cerberd v1.4.0 (go1.27.0, linux/amd64)