A command-line utility for syncing a local folder with a remote FTP or SFTP server on every change of files or directories.
Report Bug
·
Request Feature
sftp-sync is a command-line utility for syncing a local folder with a remote FTP or SFTP server on every change of files or directories.
- Continuous synchronization: Automatically syncs local changes to the remote FTP or SFTP server whenever files or directories are added, modified, or deleted.
- Exclude paths: Allows you to exclude specific paths from being synced.
- Easy to use: Simple and intuitive command-line interface.
- Protocol support: Supports both FTP and SFTP (SSH File Transfer Protocol).
- Go 1.25.0 or higher installed on your system
- Access to an (S)FTP server with valid credentials
Install the latest version directly from the repository:
go install github.com/capcom6/sftp-sync@latestThis will install sftp-sync to your $GOBIN directory. Make sure your $GOBIN is in your $PATH.
Download the pre-compiled binaries from the GitHub Releases page:
- Download the binary for your operating system and architecture
- Make the binary executable:
chmod +x sftp-sync
- Move it to a directory in your
$PATH:sudo mv sftp-sync /usr/local/bin/
If you prefer to build from source:
git clone https://github.com/capcom6/sftp-sync.git
cd sftp-sync
make buildThe binary will be available in the bin/ directory.
Run the sftp-sync command with the necessary options and arguments:
FTP:
sftp-sync --dest=ftp://username:password@hostname:port/path/to/remote/folder \
--exclude=.git /path/to/local/folderSFTP (password):
sftp-sync --dest=sftp://username:password@hostname:22/path/to/remote/folder \
--exclude=.git /path/to/local/folderSFTP (SSH key):
sftp-sync --dest="sftp://username@hostname:22/path/to/remote/folder?key=~/.ssh/id_ed25519" \
--exclude=.git /path/to/local/folderSFTP (SSH agent):
sftp-sync --dest="sftp://username@hostname:22/path/to/remote/folder?agent=true" \
--exclude=.git /path/to/local/folderNote: SFTP uses SSH port 22 by default (vs FTP port 21).
DEBUG: When set to any value, enables debug mode (equivalent to--debugflag).
--debug: Enable debug mode (can also be set viaDEBUGenvironment variable).--version: Print version information.
--dest: The destination server URL. Supports both FTP and SFTP:- FTP:
ftp://username:password@hostname:port/path/to/remote/folder - SFTP (password):
sftp://username:password@hostname:22/path/to/remote/folder - SFTP (SSH key):
sftp://username@hostname:22/path?key=~/.ssh/id_ed25519 - SFTP (SSH key with passphrase):
sftp://username@hostname:22/path?key=~/.ssh/id_ed25519&key_pass=<passphrase> - SFTP (SSH agent):
sftp://username@hostname:22/path?agent=true
- FTP:
The URL path (e.g., /path/to/remote/folder) is used as the remote destination prefix. All synced files and directories are placed relative to this path. The remote directory must already exist before starting the sync.
SFTP URL query parameters:
| Parameter | Description | Example |
|---|---|---|
key |
Path to SSH private key file (supports ~ expansion). If omitted, auto-detects ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa, ~/.ssh/id_rsa |
key=~/.ssh/custom_key |
key_pass |
Passphrase for encrypted private keys | key_pass=mysecret |
agent |
Use SSH agent for authentication when set to true |
agent=true |
Authentication methods are tried in order: SSH agent → private key → password.
Security note: Avoid putting real passwords/passphrases directly in CLI arguments when possible, as they can be exposed via shell history and process listings.
--exclude: (Optional) Specifies paths or glob patterns to exclude from synchronization. Supports*,**, and?. You can specify multiple--excludeoptions.
source: The local folder path to watch for changes (required positional argument).
The application uses structured error handling with specific exit codes:
0: Success - operation completed successfully1: Parameters Error - invalid command arguments or options2: Client Error - FTP client connection or operation failed3: Output Error - logging or output system failed4: Internal Error - unexpected internal error
- Support for patterns in the
--excludeoption. - Support of Secure FTP (SFTP) protocol.
- Improved error handling and error messages.
- Integration with Git for automatic syncing on commit or branch changes.
- Integration with Git for linking branch to remote server.
- Support for other remote protocols such as S3.
- Support for syncing specific file types or file name patterns.
- Preserve attributes (if available).
- Parallel sync in multiple threads.
- Batching events for more effective sync on frequently changes.
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open-source community a great place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion to improve this project, please fork the repository and open a pull request. You can also open an issue with the enhancement label.
If this project is useful to you, consider starring it.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the Apache License 2.0. See LICENSE for more information.
Project Link: https://github.com/capcom6/sftp-sync