Getting started

From nothing to a first synchronization: a site and its server in one command, then a preview.

Every step below works two ways. In a terminal, run sync-servers with no command and use the menus; or type the commands shown, which ask for anything you leave out. In a script, pass every value as an option and nothing is ever asked.

1. Create a site and its server

A site is a name, a local folder (the folder on this computer that holds the files you publish) and the server it is published to. One command sets up all three:

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

Or run sync-servers site add alone and answer the questions:

Site name: My Site
Local site folder [/home/<user>/sites/my-site]:
Protocol
  1. SFTP (recommended)
  2. FTPS, explicit TLS
  3. FTPS, implicit TLS
  4. FTP, insecure: sends the password in clear text
  5. Local or network folder
Choose a number [1]: 2
Host: 203.0.113.10
User: demo-user@example.com
Password:
Connecting to 203.0.113.10:21...

Use the host and user your hosting panel shows for FTP or SFTP. The Host field also takes host:port, and sftp://, ftpes:// and ftps:// addresses. Many hosts name FTP accounts in full, as demo-user@example.com. A ~ at the start of a folder is your home folder, also in cmd.exe.

The server is named after its host; rename it with sync-servers server edit. It becomes the site's Remote server, the one synchronization uses. Add more servers, such as a staging copy, with sync-servers server add, which asks the same questions; --testing makes one the Testing server.

Ways to reach a server
Protocol	Use it for
`sftp`	Most hosts. Signs in with a password, a private key file, or the SSH agent.
`ftps`	FTP with TLS started on the usual port (explicit TLS).
`ftps-implicit`	FTP over TLS from the first byte, usually on port 990.
`ftp`	Old hosts only. It sends the password in clear text, so it needs `--allow-insecure`.
`local`	A folder on this computer, a mounted drive or a network share.

To sign in with a key instead of a password: --auth key --key-path ~/.ssh/id_ed25519. The key file is read when connecting and never copied.

2. What the first connection asks

Setup connects before it saves anything, and asks only what a person has to decide:

An SSH host key seen for the first time is shown, such as ssh-ed25519 SHA256:.... Compare it with the fingerprint your host publishes, then trust it. It is pinned in the server's settings; if it ever changes, the connection stops and both fingerprints are shown. See Host keys.
A TLS certificate that does not verify is shown with the names it covers. On shared hosting it often names the hosting company's machine, such as server1.hosting.example.net, and setup offers to connect to that name instead. See Certificates.
The folder that holds the site is picked from what the server shows, starting where the account opens. Every folder is numbered, in columns when the terminal is wide enough, and folders whose names start with a dot come last:
```
Signed in as demo-user@example.com. The account opens in "/", which holds:
   1. access-logs/   5. mail/          9. .cache/       13. .trash/
   2. bin/           6. public_ftp/   10. .config/
   3. etc/           7. public_html/  11. .local/
   4. logs/          8. tmp/          12. .ssh/
  and 23 files
Site root on the server: Enter for "/", a number to open a folder, or a path [/]:
```
A number opens that folder and lists it, .. goes up, and a name or path is taken as typed once it exists; Enter takes the folder shown. Many hosting accounts open in their own folder and see it as /; a path from the control panel does not exist for them.
Deletes at the top. When the site's folder is the top of what the account sees, setup asks once whether synchronizing may delete files there. Every delete is still listed in the preview first.

When the connection fails, setup says why and offers a fix: another host, the user name and password again, or saving without testing. Cancel saves nothing.

3. Passwords

Once the server accepts the password you typed, setup offers to save it in the operating system's credential store: Windows Credential Manager, the macOS Keychain, or the Secret Service keyring on Linux. It is never written to a file, and a password the server refused is never saved. To save or change it later:

sync-servers password set Production --site "My Site"

Without a saved password you are asked for it when connecting, and an unattended run reads SYNC_SERVERS_PASSWORD. See Secrets.

4. Testing again later

sync-servers server test

The test connects, signs in, checks the root directory, and reports what the server offers: the folder the account opens in, its software, how precise its file times are, and for FTPS the TLS version. With one site, nothing needs naming. In a terminal it also fixes what it finds: a refused sign-in asks for the user name and password again, a root that is not found is picked from what the server shows, and a host that is not found can be changed. Each fix is saved.

To change a server later, sync-servers server edit asks the same questions with the current values as defaults. If sites.json itself stops loading, sync-servers config edit opens it with its problems listed.

5. Cloak what should never move

sync-servers cloak --site "My Site" .psd "archive*" /drafts/
sync-servers cloak --global .git/ node_modules/ Thumbs.db

Cloaked files are never scanned, listed, transferred or deleted, on either side. The first command cloaks for one site; the second, with --global, for every site, so files that belong to no site are cloaked once. Cloaking patterns explains the syntax, and Global patterns how a site can re-include or ignore them.

6. Preview, then synchronize

Inside the site's folder, or with only one site, the site is chosen for you:

cd ~/sites/my-site
sync-servers sync --put

--put sends newer local files to the server, --get fetches newer files from it, and --both does each. Add --delete to also remove files that are missing on the other side.

In a terminal the preview opens full screen. Each row is a file with a difference: a checkbox, an action and a status. c checks or unchecks a row and Space every row, p, g and s choose Put, Get or Skip, d shows the difference, and Enter synchronizes the checked rows after one more question. Esc leaves without changing anything.

 Synchronize: My Site -> Production (SFTP)            Put newer files to remote
 Files: 37 will be updated, 169 will be skipped, 12 need a decision
 ------------------------------------------------------------------------------
  [x] ^ Put      img/hero.svg
  [ ] ? Resolve  css/site.css        Changed locally and on the server since...
  [ ] ^ Put      .env                Matches the sensitive pattern ".env". C...

On a first sync there are no records yet, so a file that differs on both sides and has the same age asks for a decision. Files such as .env and private keys are listed unchecked. Prefer your own editor or numbered prompts? See Preview modes.

To see the preview without transferring anything, add --dry-run. In a script, sync without --yes only prints the preview.

7. Land in a site's folder

A program cannot change its shell's folder, so shell-init prints a small ssv function that does:

eval "$(sync-servers shell-init bash)"     # in ~/.bashrc; zsh is the same
ssv                                        # pick a site, land in its folder

PowerShell, fish and cmd are covered in Shell integration.

Try it without a real server

From a clone, npm run sandbox starts local SFTP, FTPS and FTP servers on 127.0.0.1 with throwaway credentials and prints the commands to add them as servers. Press Ctrl+C to stop them.