Skip to content

CLI Reference

This guide documents the command-line interfaces for both the SnapDog Server (snapdog) and the SnapDog Client (snapdog-client).

1. SnapDog Server

The snapdog server runs as a daemon that manages audio streams, routes signals to zones, and acts as the central coordinator.

Required Execution Modes

At startup, the server requires you to declare its primary configuration mode. You must specify either --config or --knx-device.

  • Configuration File Mode: Standard operation using a TOML file.
    Terminal window
    snapdog --config /path/to/snapdog.toml
  • KNX Device Mode: Bootstraps with standard defaults and relies on an ETS (Engineering Tool Software) project download over KNX routing/tunneling to configure zones and group addresses.
    Terminal window
    snapdog --knx-device

Server Arguments Reference

OptionShorthandTypeDescription
--config <PATH>-cString (Path)Path to the TOML configuration file.
--knx-device—FlagEnables KNX Device mode, causing the server to register as an ETS-programmable device.
--knx-address <ADDR>—StringThe KNX physical address (e.g. 1.1.100) to advertise in ETS. Defaults to 15.15.255. (Requires --knx-device)
--knx-prog-mode—FlagStarts the server with KNX programming mode active immediately. (Requires --knx-device)
--port <PORT>-pIntegerOverrides the HTTP API / WebUI listening port (TOML: [http].port).
--bind <IP>-bStringOverrides the network address to bind to (e.g. ::, 0.0.0.0, or a concrete interface IP).
--tls-cert <PATH>—String (Path)Path to a PEM certificate chain to enable HTTPS/TLS.
--tls-key <PATH>—String (Path)Path to an unencrypted PEM private key for HTTPS/TLS.
--codec <CODEC>—StringResampling compression codec. Options: pcm, flac, f32lz4, f32lz4e.
--sample-rate <HZ>—IntegerOutput sample resampling frequency (e.g., 44100, 48000, 96000).
--bit-depth <BITS>—IntegerOutput audio PCM bit depth. Options: 16, 24, 32.
--streaming-port <PORT>—IntegerPort for client speaker connections (TOML: [snapcast].streaming_port).
--name <NAME>—StringOverrides the server name used for mDNS, MQTT discovery, KNX device naming, and system status.
--log-level <LEVEL>-lStringLog level verbosity. Options: trace, debug, info, warn, error.
--service—FlagRuns the binary as a native NT Service. (Windows builds only)

Server Boot Examples

Launch the server on Linux or macOS with a specific configuration file:

Terminal window
snapdog --config /etc/snapdog/snapdog.toml

2. SnapDog Client

The snapdog-client player runs on speaker endpoints, connecting back to a SnapDog server to pull and play synchronized PCM audio.

Server Connection URL

The client takes an optional positional argument specifying the server connection string:

Terminal window
snapdog-client [URL]

The URL has the format <scheme>://<host>[:port], where scheme can be tcp, ws (WebSockets), or wss (Secure WebSockets).

  • mDNS Discovery (Default): If the URL argument is omitted, the client searches for a local server automatically using tcp://_snapdog._tcp.
  • Direct TCP Socket: Connects directly to the stream socket (e.g. tcp://192.168.1.50:1704).
  • WebSocket Stream: Connects over HTTP WebSockets (e.g. ws://192.168.1.50:1780 or secure wss://myname.cc).

Client Arguments Reference

OptionShorthandTypeDescription
[URL]—PositionalConnection URL. Defaults to tcp://_snapdog._tcp (mDNS).
--instance <ID>-iIntegerInstance ID when running multiple client players on the same host (default: 1).
--hostID <ID>—StringUnique host identifier. Defaults to the network card’s MAC address.
--soundcard <NAME>-sStringPCM audio output device name or index. Defaults to default.
--list-lFlagLists all available local PCM soundcard output devices and exits.
--test-tone—FlagPlays a brief audio test tone and exits to verify soundcard output.
--latency <MS>—IntegerManual latency offset in milliseconds to align with laggy hardware (default: 0).
--sampleformat <FMT>—StringForce resampler parameters in format <rate>:<bits>:<channels> (e.g., 48000:16:*).
--player <BACKEND>—StringAudio player backend and optional arguments in format <name>[:<params>|?] (e.g. alsa).
--mixer <MODE>—StringVolume mixer mode. Options: software (default), hardware:<ctrl>, midi:<params>, or none.
--cert <PATH>—String (Path)Client certificate file (PEM format) for secure connections.
--cert-key <PATH>—String (Path)Client private key file (PEM format) for secure connections.
--key-password <PW>—StringPassword for encrypted private keys.
--server-cert [PATH]—Optional String (Path)CA certificate file to verify the server certificate. Use the flag without a value to use default certificate roots.
--encryption-psk <KEY>—StringPre-shared key for stream decryption when using f32lz4e.
--daemon [PRIORITY]-dIntegerRun in the background (daemonized) with optional process priority [-20..19]. (Unix only)
--user <USER[:GROUP]>—StringSystem user and group to run as when daemonized. (Unix only)
--logsink <SINK>—StringLog sink output target: null, system, stdout, stderr, or file:<path>.
--logfilter <FILTER>—StringLog tag levels filter (default: *:info, e.g. *:debug).

Client Boot Examples

Start playing. Searches network for a SnapDog server automatically:

Terminal window
snapdog-client

Next Steps

Direct Installation Deploy background services natively or build the daemon from source.
Docker Container Run SnapDog inside a containerized setup.
Configuration Guide Customize zone names, specify speaker hardware metrics, and map smart home triggers.