CLI Reference¶

The disco binary is the management interface for the running daemon. It communicates over the Unix socket at /run/disco.sock.

Global flags¶

These flags apply to all subcommands that connect to the daemon.

The socket path is resolved in this order: --socket flag, DISCO_SOCKET environment variable, daemon.socket_path from --config, default /run/disco.sock.

disco hosts¶

List all hosts in the daemon's cache.

disco hosts
disco hosts --json

Output columns: ID (first 8 chars of machine ID), HOSTNAME, ADDRESSES, STATUS, SERVICES, LAST SEEN

Host status values:

disco hosts show¶

Show detailed information for one host. Accepts a hostname, a full machine ID (32 hex chars), or a unique machine ID prefix.

disco hosts show node1
disco hosts show a1b2c3d4
disco hosts show a1b2          # prefix match; fails if ambiguous

disco hosts forget¶

Remove a host from the cache immediately. The host will reappear if it broadcasts again.

disco hosts forget node1

disco hosts mark-lost¶

Mark a host as lost. It will be removed on the next cleanup cycle.

disco hosts mark-lost node1

disco services¶

List all services discovered across all hosts.

disco services
disco services --json

Pass a service name to show which hosts advertise it:

disco services www

disco service add¶

Tell the running daemon to advertise a new service on this host. The daemon updates its store, broadcasts immediately, and includes the service in all future announcements. Useful in ExecStartPost= of a systemd unit.

disco service add <name> <port> [--alias <alias>]

disco service add myapp 8080
disco service add myapp 8080 --alias myapp.local --alias app

disco lookup¶

Resolve a hostname to its IP addresses.

disco lookup node1

Returns one IP per line. Exits non-zero if the host is not found.

disco status¶

Show a summary of the daemon's current state.

disco status

Disco Daemon Status
------------------------------
Socket:      /run/disco.sock
Total hosts: 4
  Healthy:   3
  Stale:     1
  Lost:      0
  Static:    0

disco ping¶

Send UDP ping requests to check daemon connectivity on a remote node. The target is resolved via the daemon as a hostname, machine ID, or service name before sending.

disco ping <target> [flags]

disco ping node1
disco ping node1 --count 10 --verbose
disco ping 192.168.1.10 --port 5354

disco listen¶

Listen for raw broadcast messages on the network. Binds directly to the UDP port; no daemon connection required.

disco listen [flags]

disco listen
disco listen --json
disco listen --broadcast 192.168.1.255:5354
disco listen --key-file /etc/disco/keys.json --require-signed

disco check¶

Attempt TCP connections to all discovered services and report which are reachable.

disco check [flags]

disco check
disco check --timeout 2s --verbose
disco check --json

disco location¶

List GPS location broadcasts received by the daemon. The daemon stores the latest fix per source — each source corresponds to one GPS device on the network.

disco location
disco location --json

Output columns: SOURCE, LATITUDE, LONGITUDE, ALTITUDE, SATS, LAST SEEN

disco location show¶

Show full detail for one GPS source.

disco location show gps-timeserver
disco location show gps-pi-01 --json

disco announce¶

Send manual broadcast announcements. Does not require a running daemon.

disco announce --hostname <name> [flags]

disco announce --hostname web1
disco announce --hostname web1 --service www --port 80
disco announce --hostname web1 --count 3 --interval 2s

disco key¶

Manage cryptographic keys for message signing.

disco key generate¶

Generate a new public/private key pair and save it to a file.

disco key generate [key-file]   # default: /etc/disco/keys.json

Output includes the public key, which you distribute to trusted peers.

disco key show¶

Display the current keys and list of trusted peers from a key file.

disco key show [key-file]

disco key add-trusted¶

Add a peer's public key to the trusted list.

disco key add-trusted <public-key> [key-file]

The public key must be 64 hex characters. See How-to: Enable Security.

disco time¶

Show the current time synchronization status.

disco time

Synced: YES
Sources: 2
Offset: +0.000023 seconds
Last sync: 2026-06-13T10:30:00Z

disco timeset¶

Force the daemon to apply a time update immediately from available GPS sources.

disco timeset [flags]

disco start¶

Start the disco-daemon binary with validated flags. The daemon binary is searched in the same directory as disco, then in PATH.

disco start [daemon-flags]

Only these daemon flags are allowed:

disco config validate¶

Validate a configuration file and print a summary.

disco config validate /etc/disco/config.yaml

Exits non-zero if validation fails. Prints warnings for non-fatal issues.