Using the command-line interface

Syncthing Tray provides two command-line interfaces:

  • The separate executable syncthingctl allows you to interact with a running instance of Syncthing to trigger certain actions such as rescans, editing the Syncthing config, and more. It complements Syncthing’s own command-line interface. Invoke syncthingctl --help for details.

  • The GUI/tray executable syncthingtray also exposes a command-line interface to interact with a running instance of the GUI/tray. Invoke syncthingtray --help for details. Additional remarks:

    • If Syncthing itself is built into Syncthing Tray (like the Linux and Windows builds found in the release section on GitHub), then Syncthing’s own command-line interface is also exposed via syncthingtray.

    • The experimental mobile UI can be launched on the desktop with the qt-quick-gui subcommand when Syncthing Tray is built with support for it.

syncthingtray and syncthingctl support Bash completion when installed via GNU/Linux packaging. In case of syncthingctl the completion also works for folder and device names/IDs.

Important remarks

On Windows, you’ll have to use the syncthingtray-cli executable to see output in the terminal. (At least when using the official terminals; with, e.g., mintty, you can just use the normal executable.)

Depending on how you downloaded/installed Syncthing Tray, you may need to get syncthingctl separately, e.g., as a separate download/package.

The exact name of the executables may also differ, e.g., the Arch Linux package uses syncthingctl-qt6 and syncthingtray-qt6 for the preferable Qt 6-based version.

TLS and the certificate

Just like your web browser might ask you to accept a self-signed certificate when using TLS, syncthingctl will require you to specify the expected certificate via the --cert option.

Otherwise you will run into the error TLS error: The certificate is self-signed, and untrusted (9).

When connecting with a local Syncthing instance, syncthingctl will automatically accept the certificate that is present in the Syncthing config directory, though. This is only possible when connecting via the IP address of a local network device (e.g. 127.0.0.1).

Loading the TLS certificate can be debugged by setting the environment variable LIB_SYNCTHING_CONNECTOR_LOG_CERT_LOADING=1.

When using generic GNU/Linux executable from the GitHub release section or the website, be sure to also read the remark about OpenSSL if TLS doesn’t work.

Examples

The following sections give examples of some useful commands. For an exhaustive list of commands, use --help, as mentioned before.

syncthingtray only supports the cli subcommand for accessing Syncthing’s own CLI when Syncthing is built-in. Otherwise, you can use syncthing instead of syncthingtray in these examples.

These examples assume that Bash is used. Other shells might require different quoting/escaping.

Displaying status

One of the most useful commands is status:

syncthingctl status

It prints an accumulation of the information returned by several routes of the REST API and is comparable to the information displayed on the official web-based UI.

It is also possible to filter the output:

syncthingctl status --dir dir1 --dir dir2 --dev dev1 --dev dev2

Triggering actions

The syncthingctl commands pause, resume, and rescan are also very useful, as they allow you to quickly pause/resuming and rescanning the specified folders/devices from the command line. The help text of syncthingctl already contains some examples.

Querying and changing the configuration

You can also query and change the Syncthing configuration. Depending on the use case, either syncthingctl or Syncthing’s own CLI client is better suited.

This syncthingctl command outputs the data returned by the configuration REST API as raw JSON:

syncthingctl cat

You can use, e.g., jq to get a specific field of a specific folder:

syncthingctl cat | jq -r '.folders[] | select(.id == "docs-books-recent") | .path'

The same can be achieved using Syncthing’s own CLI client:

syncthingtray cli config folders docs-books-recent path get
syncthingtray cli config folders docs-books-recent dump-json | jq -r .path

The command syncthingctl edit allows you to edit the JSON config in a text editor on the terminal (using the editor from your EDITOR environment variable). This corresponds to changing the “Advanced Configuration” on the official web-based UI, so be careful! Incorrect configuration may damage your folder contents and render Syncthing inoperable.

It is also possible to change the config programmatically via JavaScript, e.g. this example toggles whether a specific folder is paused:

syncthingctl edit --js-lines \
    'config.folders.filter(f => f.id === "docs-misc").forEach(f => f.paused = !f.paused)'

You can use the usual JavaScript APIs, e.g. startsWith() to pause several folders at once:

syncthingctl edit --js-lines \
    'config.folders.filter(f => f.id.startsWith("docs-")).forEach(f => f.paused = !f.paused)'

You probably want to test such commands with --dry-run first before executing them for real.

Syncthing’s own CLI allows something similar without involving JavaScript:

syncthingtray cli config folders docs-misc paused set true