# 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](https://martchus.github.io/syncthingtray/#downloads-section)
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](https://docs.syncthing.net/dev/rest.html) 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](https://docs.syncthing.net/rest/config.html#rest-config)
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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/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
```