Using the command-line interface

Syncthing Tray provides two command-line interfaces:

  • The separate executable syncthingctl allows to interact with a running instance of Syncthing to trigger certain actions like 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 exposed via syncthingtray as well.

    • The experimental mobile UI can be launched on the desktop with the qt-quick-gui sub-command when Syncthing Tray was 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 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.

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 sub-command 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 with 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 quickly pausing/resuming and rescanning the specified folders/devices from the command-line. The helptext 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 e.g. 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 editing 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 a commands before executing them for real with --dry-run first.

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

syncthingtray cli config folders docs-misc paused set true