cmd-sync-servers

Examples

Commands for common jobs, ready to adapt. Each one acts on the site of the current folder unless it names one with --site.

Set up a site over FTPS

One command sets up the site and its server, connects, and lets you pick the site's folder from what the server shows.

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

On Windows, in cmd.exe:

sync-servers site add --name "My Site" --local-root "C:\Users\<user>\Sites\my-site" ^
  --protocol ftps --host 203.0.113.10 --user demo-user@example.com

On shared hosting the certificate often names the hosting company's machine, such as server1.hosting.example.net, not the address you typed. Setup then shows the certificate and offers to connect to that name, which keeps full verification, to check the certificate as that name, or to trust this certificate. See Certificates and site add.

Set up a site over SFTP with a key

SFTP is the default protocol. The first connection shows the server's host key: compare it with the fingerprint your host publishes before you trust it.

sync-servers site add --name "My Site" --local-root ~/sites/my-site \
  --host sftp.example.com --user demo-user \
  --auth key --key-path ~/.ssh/id_ed25519 --remote-root /var/www/my-site

On Windows, in cmd.exe:

sync-servers site add --name "My Site" --local-root "C:\Users\<user>\Sites\my-site" ^
  --host sftp.example.com --user demo-user ^
  --auth key --key-path "C:\Users\<user>\.ssh\id_ed25519" --remote-root /var/www/my-site

A key with a passphrase asks for it, or reads SYNC_SERVERS_KEY_PASSPHRASE. --auth agent uses your SSH agent instead. See Host keys.

Add a Staging server

A site has one Remote server, which sync uses, and may have a Testing server, where the VS Code extension uploads files on save.

sync-servers server add --name Staging --host 192.0.2.20 --user demo-user \
  --remote-root /var/www/staging --testing
sync-servers server set-testing --clear

The second line takes the Testing role away again; server set-remote Staging would make it the server sync uses. See server add.

Put one folder or one file

A path limits the preview to that part of the site. put sends at once, with a preview only when a file changed on both sides.

sync-servers sync --put css
sync-servers put index.html

See sync and put.

Get files from the server

The same, the other way: files that are newer on the server come down.

sync-servers sync --get
sync-servers get img

Local files a get replaces are kept in the recovery folder for 14 days. See get.

Delete server files that are gone locally

--delete also lists the files on the server that no longer exist on your computer. Look first with --dry-run, which moves nothing.

sync-servers sync --put --delete --dry-run
sync-servers sync --put --delete

Files that were never synchronized stay unchecked, so you decide each one. A run that would delete more than 50 files, or more than 25 percent of the files on that side, asks you to confirm the count first; --allow-mass-delete lets a script go past that limit. See Synchronization.

Check what changed, moving nothing

sync-servers status
sync-servers diff css/site.css

status lists what changed on each side since the last sync, and diff shows how the two copies of one file differ. See status.

Review the preview in your editor

The preview becomes a text file: check or uncheck rows, change the action words, then save and close to synchronize. Closing without saving cancels.

sync-servers sync --put --preview editor

An editor that returns at once needs its wait flag, as VS Code does:

export SYNC_SERVERS_EDITOR="code --wait"

On Windows, in cmd.exe:

set "SYNC_SERVERS_EDITOR=code --wait"

See Editor mode.

Use plain prompts

Numbered rows and typed commands, with no full-screen drawing, for screen readers and logging terminals.

sync-servers sync --put --plain

In the preview, 2-6 checks or unchecks rows, p 3 puts row 3, go synchronizes and q cancels. SYNC_SERVERS_UI=plain makes it the default. See Plain mode.

Run unattended, in a script or CI

--yes runs without a preview, the password comes from the environment, and --json prints one document a script can read.

export SYNC_SERVERS_PASSWORD="$FTP_PASSWORD"
sync-servers sync --site "My Site" --put --yes --json

Or save a plan for review and run exactly that plan later; it is refused if the site or the server changed in between:

sync-servers sync --put --plan-out plan.json
sync-servers sync --put --plan-in plan.json --yes

A script cannot answer a question about a new host key or certificate: connect once in a terminal first, or pass --host-key or --trust-certificate with the fingerprint. The exit code is 0 when everything ran, 3 when rows failed or wait for a decision, 4 when cancelled and 5 when a safety guard stopped the run. See Unattended runs and Exit codes.

Cloak in one site or in every site

Cloaked files are never scanned, listed, transferred or deleted.

sync-servers cloak .psd "archive*"                  # in this site
sync-servers cloak --global .git/ node_modules/      # in every site
sync-servers cloak "!node_modules/"                  # this site keeps node_modules/ after all
sync-servers cloak --ignore-global                   # or ignores the global patterns
sync-servers cloak --list

See Cloaking and Global patterns.

A site whose folder links to files kept elsewhere, such as fonts shared by several sites, can put and get them as if they were its own. The server gets ordinary files; a Get writes the file a link points to and keeps the link.

sync-servers site edit --symlinks follow        # every link; follow-inside-root keeps to the site's folder
sync-servers sync --put --dry-run               # the preview marks rows reached through a link out of the site

See Symbolic links.

Record files as in sync

When both copies are already the same, for example after a site was copied to the server another way, record them as in sync so the next sync starts from there.

sync-servers mark-synced .

See mark-synced.

Change to a site's folder from anywhere

A program cannot change its shell's folder, so shell-init prints a small ssv function that does. For bash, in ~/.bashrc:

eval "$(sync-servers shell-init bash)"

In cmd.exe, with %USERPROFILE%\bin on your PATH:

sync-servers shell-init cmd > "%USERPROFILE%\bin\ssv.cmd"

Then ssv opens the sites and lands in the folder of the one you open. See Shell integration.

Start over with one server

Forget what the last sync recorded for the site and its server, so the next sync compares both sides as if for the first time.

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

See state reset.