Installing Synck

Synck is a single program, synck, written in Rust. You can install a published release, which needs nothing but a terminal, or build it from source, which takes a few minutes the first time.

Install a published release

On macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/synergyos/synck/main/install.sh | sh

On Windows, in PowerShell 5.1 or newer:

irm https://raw.githubusercontent.com/synergyos/synck/main/install.ps1 | iex

The installer downloads the latest published release for your platform, checks it against the release’s SHA256SUMS.txt, and installs it in ~/.local/bin/synck on macOS and Linux, or %LOCALAPPDATA%\Synck\bin\synck.exe on Windows. It stops before replacing anything if the download or the check fails. It does not change your PATH: if your shell cannot find synck afterwards, add that directory to it and open a new terminal. Releases are built for Linux x86_64 with glibc 2.39 or newer, macOS 12 or newer on Apple Silicon and Intel, and Windows x86_64. On anything else, build from source.

Build from source

You need three things:

  1. Git, to download the source.
  2. Rust, installed through rustup. The source tree names the exact compiler version it was tested with in rust-toolchain.toml, and rustup downloads that version automatically the first time you build.
  3. A C compiler and linker. Some of Synck’s dependencies, including the SQLite database it bundles, contain C code:
    • macOS: the Xcode Command Line Tools (xcode-select --install).
    • Linux: your distribution’s C build tools, for example build-essential on Debian and Ubuntu or gcc on Fedora.
    • Windows: the Microsoft C++ Build Tools, which the rustup installer offers to set up for you.

Then download the source and install the command:

git clone https://github.com/synergyos/synck.git
cd synck
cargo install --locked --path crates/synck-local

--locked makes Cargo use exactly the dependency versions recorded in Cargo.lock, which are the versions the release was tested with. Cargo places the finished synck program in its binary directory: ~/.cargo/bin on macOS and Linux, %USERPROFILE%\.cargo\bin on Windows. rustup normally adds that directory to your PATH. If your shell cannot find synck afterwards, open a new terminal, or add the directory to PATH yourself.

Check the installation

Whichever way you installed it, check that it works:

$ synck --version
synck 0.3.0

Synck keeps no global settings and has nothing to configure after installation. Every repository carries its own configuration inside its .synck directory.

Getting help

The tool documents itself. synck --help lists every command, and every command and subcommand accepts --help:

$ synck mv --help
Move a tracked item and preserve its identity

Usage: synck mv [OPTIONS] --message <MESSAGE> <SOURCE> <DESTINATION>
...

synck instructions prints a compact operating guide that covers the safe way to work with repositories and their copies. It is written for people and for AI agents that drive the CLI on someone’s behalf, and it is worth reading once.

A note on the examples

The examples in this documentation use a POSIX shell such as zsh or bash, as on macOS and Linux. Synck commands are the same on Windows. Only the surrounding shell commands, such as printf, cat and mkdir, differ, and PowerShell has equivalents for all of them.

Example output is real. IDs, hashes and timestamps will be different on your machine, because Synck generates fresh IDs and records the actual time.

Updating and removing

To update a published release, run the installer again. To update a build from source, fetch the new source and install again. --force replaces the installed program even when the version number has not changed:

cd synck
git pull
cargo install --locked --path crates/synck-local --force

Updating the tool never rewrites your repositories. Before 1.0, though, each release reads only its own repository format, so check formats and compatibility before you move to a release with a new one. To remove Synck, delete the installed program, or run cargo uninstall synck-local for a build from source. Your repositories are ordinary folders and are not affected.

A background helper you might notice

When you work in a tracked folder, Synck starts a small background process, synck monitor, that watches the folder for changes so that synck status and synck commit stay fast in large folders. It holds no data of its own and is safe to stop at any time:

$ synck monitor status
monitor running
$ synck monitor stop
monitor stopped

Synck starts it again the next time a command needs to scan the folder.

Now create your first repository.