Skip to content
Beta

CLI Reference

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

1. SnapDog Server

Section titled “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

Section titled “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

Section titled “Server Arguments Reference”
Option Shorthand Type Description
--config <PATH> -c String (Path) Path to the TOML configuration file.
--knx-device — Flag Enables KNX Device mode, causing the server to register as an ETS-programmable device.
--knx-address <ADDR> — String The KNX physical address (e.g. 1.1.100) to advertise in ETS. Defaults to 15.15.255. (Requires --knx-device)
--knx-prog-mode — Flag Starts the server with KNX programming mode active immediately. (Requires --knx-device)
--port <PORT> -p Integer Overrides the HTTP API / WebUI listening port (TOML: [http].port).
--bind <IP> -b String Overrides 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> — String Resampling compression codec. Options: pcm, flac, f32lz4, f32lz4e.
--sample-rate <HZ> — Integer Output sample resampling frequency (e.g., 44100, 48000, 96000).
--bit-depth <BITS> — Integer Output audio PCM bit depth. Options: 16, 24, 32.
--streaming-port <PORT> — Integer Port for client speaker connections (TOML: [snapcast].streaming_port).
--name <NAME> — String Overrides the server name used for mDNS, MQTT discovery, KNX device naming, and system status.
--log-level <LEVEL> -l String Log level verbosity. Options: trace, debug, info, warn, error.
--service — Flag Runs the binary as a native NT Service. (Windows builds only)

Server Boot Examples

Section titled “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

Section titled “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

Section titled “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

Section titled “Client Arguments Reference”
Option Shorthand Type Description
[URL] — Positional Connection URL. Defaults to tcp://_snapdog._tcp (mDNS).
--instance <ID> -i Integer Instance ID when running multiple client players on the same host (default: 1).
--hostID <ID> — String Unique host identifier. Defaults to the network card’s MAC address.
--soundcard <NAME> -s String PCM audio output device name or index. Defaults to default.
--list -l Flag Lists all available local PCM soundcard output devices and exits.
--test-tone — Flag Plays a brief audio test tone and exits to verify soundcard output.
--latency <MS> — Integer Manual latency offset in milliseconds to align with laggy hardware (default: 0).
--sampleformat <FMT> — String Force resampler parameters in format <rate>:<bits>:<channels> (e.g., 48000:16:*).
--player <BACKEND> — String Audio player backend and optional arguments in format <name>[:<params>|?] (e.g. alsa).
--mixer <MODE> — String Volume 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> — String Password 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> — String Pre-shared key for stream decryption when using f32lz4e.
--daemon [PRIORITY] -d Integer Run in the background (daemonized) with optional process priority [-20..19]. (Unix only)
--user <USER[:GROUP]> — String System user and group to run as when daemonized. (Unix only)
--logsink <SINK> — String Log sink output target: null, system, stdout, stderr, or file:<path>.
--logfilter <FILTER> — String Log tag levels filter (default: *:info, e.g. *:debug).

Client Boot Examples

Section titled “Client Boot Examples”

Start playing. Searches network for a SnapDog server automatically:

Terminal window
snapdog-client

Next Steps

Section titled “Next Steps”
Direct InstallationDeploy background services natively or build the daemon from source.
Docker ContainerRun SnapDog inside a containerized setup.
Configuration GuideCustomize zone names, specify speaker hardware metrics, and map smart home triggers.