Options
Everything that changes how sync-servers runs, in one place: options on the command line, environment variables, and the ways a preview can be shown. The settings kept in sites.json are on Configuration.
Global options
Every command takes these, before or after its own options.
| Option | Does |
|---|---|
--site <name> | The site to work on, by name or id |
--server <name> | The server to work on, by name or id |
--config-dir <folder> | Use this settings folder |
--state-dir <folder> | Use this state folder |
--json | Write one JSON document to stdout |
--plain | Use numbered line prompts, never a full-screen interface |
--ascii | Use ASCII symbols only |
--no-color | Turn colour off (NO_COLOR does too) |
--debug | Also log details to stderr, with secrets removed |
--cd-file <file> | Write the chosen site folder here, for shell integration |
--version | Print the version and exit |
-h, --help | Print help and exit |
Command options from A to Z
Each option once, with what it does and the commands that take it. sync-servers <command> --help lists the options of one command.
| Option | Does | Commands |
|---|---|---|
--allow-insecure | Allow plain FTP, which sends the password in clear text | site add, server add, server edit |
--allow-mass-delete | Run deletes past the mass-delete limit without asking | sync |
--allow-root-deletes | Allow deletes when the remote root is "/" or a drive root | site add, server add, server edit |
--auth <method> | password, key or agent (key and agent are SFTP only) | site add, server add, server edit |
--both | Get and put newer files | sync |
--ca-file <file> | FTPS: a PEM file of extra certificate authorities | site add, server add, server edit |
--cache | Cache local scans between runs (--no-cache to turn off) | site edit |
--case-sensitive | Treat file names as case-sensitive (--no-case-sensitive to turn off) | site edit |
--clear | Leave the site without a Testing server | server set-testing |
--delete | Delete files missing on the other side (never-synchronized ones stay unchecked) | sync |
--dir-mode <mode> | Permissions for created folders, such as 755 | site add, server add, server edit |
--disable | Turn cloaking off for the site, keeping its patterns | cloak |
--dry-run | Show the preview and transfer nothing | sync |
--editor | Edit the whole server as JSON in your editor | server edit |
--editor | Edit the whole site as JSON in your editor | site edit |
--enable | Turn cloaking on for the site | cloak |
--file-mode <mode> | Permissions for uploaded files, such as 644 | site add, server add, server edit |
--forget-certificate | Remove the trusted TLS certificate; the next connection verifies it again | server edit |
--forget-host-key | Remove the pinned SSH host key, after checking the new one with the host | server edit |
--get | Get newer files from the server | sync |
--global | Work on the global patterns, which every site uses before its own | cloak, uncloak |
--host <host> | The host name or IP address; host:port and sftp://, ftps:// and ftpes:// addresses work too | site add, server add, server edit |
--host-key <fingerprint> | Accept this SSH host key (SHA256:...) when it is not pinned yet | sync, put, get, status, diff, mark-synced |
--host-key <fingerprint> | Accept this SSH host key (SHA256:...) when it is not pinned yet, for scripts | server test |
--ignore-global | Stop using the global patterns in the site | cloak |
--ip-family <4|6> | Connect over IPv4 or IPv6 only | site add, server add, server edit |
--key-path <file> | The private key file for --auth key | site add, server add, server edit |
--kind <kind> | password (default) or passphrase, for a private key | password set |
--kind <kind> | password or passphrase; both when not given | password forget |
--legacy-algorithms | SFTP: allow older algorithms for an old server | site add, server add, server edit |
--list | Show the cloaking settings | cloak |
--local-root <folder> | Move the local site folder | site edit |
--local-root <folder> | The local site folder, which must exist | site add |
--name <name> | Rename the site | site edit |
--name <name> | The server name, unique within the site (default: the host) | server add, server edit |
--name <name> | The site name, unique ignoring case | site add |
--path | Treat every argument as a path inside the local root | cloak, uncloak |
--pattern | Treat every argument as a pattern | cloak, uncloak |
--plan-in <file> | Run a saved plan, if the site and server have not changed since | sync |
--plan-out <file> | Save the plan as JSON | sync |
--port <port> | The port, when not the protocol default | site add, server add, server edit |
--preview <mode> | Show the preview in the terminal UI (tui), your editor, plain prompts, or print it (none) | sync, put, get |
--protocol <protocol> | sftp (default), ftps, ftps-implicit, ftp or local | site add, server add, server edit |
--put | Put newer files to the server | sync |
--remote | Make it the site's Remote server, used to synchronize | server add |
--remote-root <path> | The site root on the server; for local, a folder | site add, server add, server edit |
--save-password | Keep the password in the OS credential store (--no-save-password to stop) | site add, server add, server edit |
--server-name <name> | The name of the first server (default: its host) | site add |
--stdin | Read it from standard input instead of asking | password set |
--symlinks <policy> | Symbolic links in the local folder: skip them (skip), follow those inside the site (follow-inside-root), or follow all (follow) | site edit |
--testing | Make it the site's Testing server | server add |
--timeout <seconds> | Seconds to wait for the server (default 30) | site add, server add, server edit |
--tls-min-version <version> | FTPS: TLSv1.2 (default) or TLSv1.3 | site add, server add, server edit |
--tls-servername <host> | FTPS: the name to verify the certificate against | site add, server add, server edit |
--trust-certificate <sha256> | Accept this TLS certificate (SHA-256 fingerprint) when it does not verify | sync, put, get, status, diff, mark-synced |
--trust-certificate <sha256> | Accept this TLS certificate (SHA-256 fingerprint) when it does not verify, for scripts | server test |
--upload-on-save | Upload files when they are saved in the VS Code extension | site add, server add, server edit |
--use-global | Use the global patterns in the site, as sites do unless told otherwise | cloak |
--user <name> | The user name | site add, server add, server edit |
--web-url <url> | The local web address, such as http://localhost:8080/ | site edit |
--web-url <url> | The web address of the site on this server | site add, server add, server edit |
-y, --yes | Do not ask for confirmation | site remove, server remove |
-y, --yes | Run without asking for confirmation | sync, put, get, state reset |
Environment variables
| Variable | Does |
|---|---|
SYNC_SERVERS_HOME | Moves the settings folder there, and the state folder to its state folder. |
SYNC_SERVERS_SITE | The site to use when a command names none, by name or id. |
SYNC_SERVERS_PASSWORD | The password of the server in use, for unattended runs. A saved password comes first. |
SYNC_SERVERS_KEY_PASSPHRASE | The passphrase of the private key of the server in use. |
SYNC_SERVERS_KEYRING | off, 0, false or no turns the operating system's credential store off. |
SYNC_SERVERS_UI | How previews are shown when --preview is not given: tui, editor, plain or none. |
SYNC_SERVERS_EDITOR | The editor for editor mode, --editor and config edit, with its arguments, such as code --wait. |
VISUAL, EDITOR | The editor when SYNC_SERVERS_EDITOR is not set, in that order. Without any, Notepad on Windows, then nano or vi. |
SSH_AUTH_SOCK | The SSH agent for the agent sign-in method. On Windows the OpenSSH agent is used when it is not set. |
NO_COLOR | Any value but an empty one turns colour off, as --no-color does. Nothing depends on colour. |
TERM=dumb | ASCII symbols and plain prompts, with no full-screen drawing. |
Setting one for a single command:
SYNC_SERVERS_UI=plain sync-servers sync --putIn cmd.exe, for the rest of the session:
set "SYNC_SERVERS_UI=plain"
sync-servers sync --putPreview modes
sync, and put or get when a decision is needed, show a preview before anything moves. --preview chooses how:
| Mode | Shows the preview |
|---|---|
tui | Full screen, row by row. The default in a terminal. |
editor | As a text file in your editor; see Editor mode. |
plain | As numbered rows and typed commands; see Plain mode. |
none | Printed, then one yes or no question in a terminal. The default without a terminal. |
Without --preview, the mode is none when nobody can answer: with --yes, --dry-run, --json, or no terminal. Otherwise it comes from SYNC_SERVERS_UI, else tui, which becomes plain with --plain, with TERM=dumb, or in a terminal that cannot take single key presses.