Command line

The program is sync-servers. With no command in a terminal it opens the full-screen interface; every task is also a command, for scripts and for anyone who prefers typing.

• Commands
• Preview modes
• The terminal interface
• Editor mode
• Plain mode
• Unattended runs
• Shell integration
• Exit codes
• JSON output

Commands

This reference is generated from the same definitions as sync-servers --help; sync-servers <command> --help prints the part for one command. A command acts on the site of the current folder unless it is given --site; see Which site a command means.

• sites: List the sites
• site add: Add a site and its first server; in a terminal, connect first and pick the root from the server
• site edit: Change a site, with options or as JSON in your editor
• site show: Show a site and its servers
• site remove: Remove a site, its saved passwords and its sync records
• site path: Print a site's local root (with shell integration, change to it)
• server list: List a site's servers
• server add: Add a server to a site; in a terminal, connect first and pick the root from the server
• server edit: Change a server: asks again in a terminal, or takes options, or JSON in your editor
• server remove: Remove a server, its saved passwords and its sync records
• server test: Connect, sign in, check the remote root and show what the server offers; in a terminal, fix what it finds
• server set-remote: Make a server the one synchronization uses
• server set-testing: Make a server the Testing server, or clear the role
• password set: Save a password or key passphrase in the OS credential store
• password forget: Remove a saved password or key passphrase
• cloak: Cloak files and folders so no operation touches them, in one site or every site, or list what is cloaked
• uncloak: Remove cloaked paths or patterns, from one site or from the global patterns
• sync: Synchronize a site with its Remote server: preview, then transfer
• put: Put files or folders now, with a preview only when a decision is needed
• get: Get files or folders now, with a preview only when a decision is needed
• status: Show what changed on each side since the last sync; transfers nothing
• diff: Show how the local and remote copies of a file differ
• mark-synced: Record files as in sync without transferring them
• state reset: Forget the sync records of a site and server; the next sync starts from scratch
• config path: Show the folders sync-servers reads and writes
• config edit: Edit the whole sites.json in your editor, also when it is not valid
• doctor: Check Node.js, the folders, the credential store, the terminal and every site
• shell-init: Print the "ssv" shell function that changes to a chosen site's folder (bash, zsh, fish, pwsh, cmd)
• help: Show help for a command

Global options

Every command takes these.

sync-servers sites
sync-servers sites --json

sync-servers site add
sync-servers site add --name "My Site" --local-root ~/sites/my-site --protocol ftps --host 203.0.113.10 --user demo-user@example.com
sync-servers site add --name "My Site" --local-root ~/sites/my-site --host sftp.example.com --user demo-user --remote-root /var/www/my-site

sync-servers site edit "My Site" --name "Sample App"
sync-servers site edit --local-root ~/sites/my-site
sync-servers site edit --symlinks follow-inside-root
sync-servers site edit --editor

sync-servers site show
sync-servers site show "My Site" --json

sync-servers site remove "My Site"
sync-servers site remove "My Site" --yes

sync-servers site path "My Site"
ssv site path "My Site"

sync-servers server list
sync-servers server list --site "My Site" --json

sync-servers server add
sync-servers server add --name Production --host sftp.example.com --user demo-user --remote-root /var/www/my-site
sync-servers server add --name Staging --host ftpes://ftp.example.org --user demo-user --remote-root /public --testing

sync-servers server edit Production
sync-servers server edit Production --port 2222
sync-servers server edit Production --forget-host-key
sync-servers server edit Production --forget-certificate
sync-servers server edit --editor

sync-servers server remove Staging
sync-servers server remove Staging --site "My Site" --yes

sync-servers server test
sync-servers server test Production --site "My Site"
sync-servers server test --host-key SHA256:<fingerprint>
sync-servers server test --trust-certificate 3A:91:5C:<...>:C4

sync-servers server set-remote Production

sync-servers server set-testing Staging
sync-servers server set-testing --clear

sync-servers password set Production
printf %s "$SECRET" | sync-servers password set Production --stdin

sync-servers password forget Production

sync-servers cloak .psd "archive*" node_modules/
sync-servers cloak img/raw
sync-servers cloak --global .git/ node_modules/
sync-servers cloak --list

sync-servers uncloak .psd
sync-servers uncloak img/raw
sync-servers uncloak --global node_modules/

sync-servers sync --put
sync-servers sync --both --delete --dry-run
sync-servers sync --put --preview editor
sync-servers sync --get css img --yes
sync-servers sync --put --plan-out plan.json

sync-servers put css/site.css
sync-servers put img --site "My Site"

sync-servers get css/site.css
sync-servers get img --site "My Site"

sync-servers status
sync-servers status css --json

sync-servers diff css/site.css

sync-servers mark-synced css/site.css
sync-servers mark-synced .

sync-servers state reset
sync-servers state reset --site "My Site" --yes

sync-servers config path
sync-servers config path --json

sync-servers config edit

sync-servers doctor
sync-servers doctor --json

eval "$(sync-servers shell-init bash)"
sync-servers shell-init fish > ~/.config/fish/functions/ssv.fish
Invoke-Expression (& sync-servers shell-init pwsh | Out-String)

sync-servers help server add

Preview modes

sync, and put or get when a decision is needed, show a preview before anything moves. --preview chooses how:

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 be put in raw mode. --yes together with a preview mode is a usage error.

The terminal interface

Run sync-servers with no command. It opens at the site of the current folder, or at the list of sites. Everything works from the keyboard at 80 by 24, and ? on any screen lists every key of that screen. --ascii uses ASCII symbols only, and --no-color or NO_COLOR turns colour off; every symbol stands beside a word, so nothing is lost.

Every screen has the same frame. Two solid lines frame the content. While rows are hidden above or below what is shown, a dashed line marks that edge; at the first or last row it disappears. Under the bottom line, the menu lists the screen's keys as key = action, with a pipe between them, wrapping onto more rows on a narrow terminal. The last row shows messages, the progress of a running task, or the full text of the focused row.

 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 ______________________________________________________________________________
  Space = CHECK/UNCHECK ALL  |  c = Check/Uncheck  |  p = Put  |  g = Get
  s = Skip  |  d = Diff  |  a = All  |  q = Quit  |  Enter = Synchronize
 css/site.css

While a text field has focus, typed characters go into it; Ctrl+U clears it.

The terminal is restored on every way out: a normal exit, Ctrl+C, a signal, or an error.

Editor mode

--preview editor, or SYNC_SERVERS_UI=editor, writes the plan to a private temporary file and opens it in the first of SYNC_SERVERS_EDITOR, VISUAL and EDITOR, else Notepad on Windows or nano, then vi, elsewhere. An editor that returns at once, such as VS Code, needs its wait flag: SYNC_SERVERS_EDITOR="code --wait".

# sync-servers preview: My Site -> Production (SFTP)
# Put newer files to remote
# Files: 37 will be updated, 169 will be skipped, 12 need a decision
#
# Check or uncheck a box, or change the action word, then save and close to
# synchronize. Close without saving, or delete every row, to cancel.
#   put  get  skip  synced  delete-remote  delete-local
#
[x] put       1  img/hero.svg
[ ] resolve   3  css/site.css      # Changed locally and on the server.
[ ] put       4  .env              # Matches the sensitive pattern ".env".

The number identifies the row; the path is there to read and is checked against the number. A deleted row is skipped. A number the plan does not hold, a changed path, an unknown action, an action the file cannot take, or a resolve row left checked reopens the file with the problems as comments at the top. An edit can only choose among the planned rows; it can never add a path.

Plain mode

--plain, TERM=dumb, or a terminal without raw mode runs every flow as numbered prompts, with no alternate screen and no cursor movement, which screen readers and logging terminals follow. With no command it shows the sites as a numbered list and a menu for the chosen site. The preview prints numbered rows and takes commands:

Unattended runs

• Without a terminal, nothing ever asks. A secret that cannot be found fails with E_AUTH; an unknown SSH host key is refused unless --host-key names it.
• sync without --yes prints the preview and transfers nothing, so a script that forgets the flag does no harm.
• --yes runs the checked rows. Rows that need a decision are never decided for you: they are reported, and the exit code is 3.
• Deletes run only with both --delete and --yes, and past the mass-delete limit only with --allow-mass-delete as well.
• --plan-out plan.json saves the plan; --plan-in plan.json runs it later, after checking that a fresh scan still matches what the plan was built from.

SYNC_SERVERS_PASSWORD="$DEPLOY_PASSWORD" \
  sync-servers sync --put --yes --site "My Site" --host-key SHA256:<fingerprint>

Shell integration

A program cannot change its shell's folder. sync-servers shell-init <shell> prints a small ssv function that runs sync-servers with --cd-file and then changes to the folder of the site you chose. It changes folder only to an existing local folder of a configured site.

Then ssv opens the sites and lands in the one you open, and ssv site path "My Site" goes straight there.

Exit codes

JSON output

--json writes one JSON document to standard output and nothing else; progress and warnings go to standard error. Every document names its kind and version, so a script can tell when the shape changes:

{
  "schema": "sync-servers/status@1",
  "siteId": "3f2b7c1e-8a4d-4f6b-9c2e-1d5a7b9e0c31",
  "local": [{ "path": "css/site.css", "state": "local-changed" }],
  ...
}

The kinds are sites, site, site-removed, site-path, servers, server, server-removed, server-test, cloaking, cloaking-global, sync, status, diff, mark-synced, config-paths, doctor and error. Paths are site-relative, and secrets never appear.