1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
# 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
```
|
