CLI Flags and Environment Variables
Syncthing's CLI has changed significantly since v1.20. The modern syncthing serve subcommand replaces the old syncthing root invocation for running the daemon. This reference covers all stable flags and environment variables.
Learning Focus
In systemd units, use environment variables for configuration that varies by environment (API keys, log level). Use CLI flags only for immutable startup behavior (home dir, no-browser).
Subcommands
| Subcommand | Purpose |
|---|---|
syncthing serve | Start the Syncthing daemon (primary command) |
syncthing generate | Generate a config and cert without starting |
syncthing decrypt | Decrypt a receive-encrypted folder (for recovery) |
syncthing --version | Print version and exit |
syncthing --device-id | Print the Device ID and exit |
syncthing serve Flags
syncthing serve [flags]
| Flag | Default | Description |
|---|---|---|
--home=PATH | ~/.local/share/syncthing | Path to config/data directory |
--config=PATH | $HOME/config.xml | Explicitly set config file path |
--data=PATH | Same as --home | Separate path for database files |
--no-browser | false | Do not open the web browser on startup |
--no-restart | false | Do not auto-restart after crash (systemd handles this) |
--logfile=PATH | (stdout) | Write logs to a file instead of stdout |
--logflags=N | 3 | Bitmask for log line prefix: 0=none, 1=date, 2=time, 3=date+time |
--log-max-size=N | 10485760 (10 MB) | Max log file size before rotation |
--log-max-old-files=N | 3 | Number of rotated log files to keep |
--allow-newer-config | false | Allow config written by a newer version |
--gui-address=ADDR | 127.0.0.1:8384 | Override GUI/API bind address |
--gui-apikey=KEY | (from config) | Override API key for this session |
Common Usage Patterns
serve-examples.sh
# Standard production startup (no browser, systemd handles restart)
syncthing serve --no-browser --no-restart --logflags=0
# Custom home directory (e.g., for a system user)
syncthing serve --home=/home/syncthing/.local/share/syncthing --no-browser
# Bind GUI to a different port
syncthing serve --no-browser --gui-address=127.0.0.1:9999
# Override API key (useful for one-off scripting)
syncthing serve --no-browser --gui-apikey=temporarykey123
# Generate verbose debug output
STTRACE=all syncthing serve --no-browser 2>&1 | tee /tmp/syncthing-debug.log
syncthing generate Flags
Generate a config and TLS certificate without running:
generate-examples.sh
# Generate in the default home directory
syncthing generate
# Generate in a custom directory
syncthing generate --home=/opt/syncthing-data
# Generate without user interaction (for scripted deployments)
syncthing generate --no-default-folder
syncthing decrypt Flags
Recover files from a receiveencrypted folder:
decrypt-examples.sh
# Decrypt files from an encrypted repository (requires encryption password)
syncthing decrypt \
--from=/mnt/encrypted-backup \
--to=/tmp/recovered \
--password=yourFolderEncryptionPassword \
--verify-only # Dry run — verify without writing
Environment Variables
| Variable | Effect |
|---|---|
STNOUPGRADE | Set to 1 to disable the built-in auto-upgrade (recommended in package-managed installs) |
STLEVEL | Set log verbosity: verbose, debug |
STTRACE | Comma-separated trace categories (e.g., beacon,db,protocol). all for everything. |
STPROFILER | Address to start Go pprof HTTP profiler (e.g., 127.0.0.1:6060) |
GOMAXPROCS | Limit Go runtime parallelism (e.g., 2 to cap at 2 threads) |
STGUIADDRESS | Override GUI bind address (alternative to --gui-address) |
STGUIAPIKEY | Override GUI API key (alternative to --gui-apikey) |
STNODEFAULTFOLDER | Set to 1 to skip creating the default ~/Sync folder on first run |
HOME | Standard Linux home dir — affects default config path if --home not set |
Systemd Service Environment Example
/etc/systemd/system/syncthing@.service (relevant section)
[Service]
User=%I
Environment=STNOUPGRADE=1
Environment=GOMAXPROCS=2
Environment=STLEVEL=info
ExecStart=/usr/bin/syncthing serve --no-browser --no-restart --logflags=0
Trace Categories for Debugging
When setting STTRACE:
| Category | What It Logs |
|---|---|
beacon | Local discovery beacon traffic |
db | Database read/write operations |
protocol | BEP protocol messages between peers |
model | File model sync decisions |
net | Network connection events |
relay | Relay server interactions |
upnp | UPnP port mapping attempts |
versioner | File versioning operations |
debug-protocol.sh
# Trace only protocol and relay for connection debugging
STTRACE=protocol,relay syncthing serve --no-browser 2>&1 | grep -E "\[TRACE\]"
Flag Precedence
flowchart LR
CLI[CLI Flags] --> ENV[Environment Variables]
ENV --> CONF[config.xml values]
CONF --> DEFAULTS[Built-in defaults]
CLI -- highest priority --> CONF
CLI flags take highest precedence, followed by environment variables, then config.xml, then compiled defaults.