Docs/Getting started

Install the CLI

The syn command line tool and the synchronoid Python SDK are distributed together. Pick the install method that fits your setup.

Requirements

Python 3.10, 3.11, 3.12 or 3.13 (needed to run projects locally).
Linux (x86-64 and ARM64), macOS 13 or newer, or Windows 11 with WSL 2.
Outbound HTTPS access to api.synchronoid.com and app.synchronoid.com.

Install methods

Use pip inside a virtual environment. This is the best choice when your project code imports synchronoid.

terminal

$ python -m venv .venv
$ source .venv/bin/activate
$ pip install synchronoid

pipx installs the CLI in its own isolated environment and puts syn on your path. Use it for a machine-wide CLI.

terminal

$ pipx install synchronoid

The Homebrew formula installs a self-contained CLI with its own Python, so no local Python is needed to deploy.

terminal

$ brew tap synchronoid/tap
$ brew install syn

The image is useful in CI. Mount your project and a config directory for the login token.

terminal

$ docker pull ghcr.io/synchronoid/syn:0.14
$ docker run --rm -it \
    -v "$PWD":/project -w /project \
    -e SYN_TOKEN \
    ghcr.io/synchronoid/syn:0.14 deploy

Verify the installation

terminal

$ syn --version
syn 0.14.2 (sdk 0.14.2, python 3.12.4)
$ syn doctor
OK   python version
OK   can reach api.synchronoid.com
OK   credentials (run "syn login")

syn doctor checks Python, network access and credentials, and prints a hint for each problem.

Versions and compatibility

Synchronoid is in beta, so the CLI, SDK and platform are released together. The platform supports the current minor version and the one before it.

Version	Status	Notes
`0.14.x`	Current	Latest features and fixes.
`0.13.x`	Supported	Security and critical fixes only.
`0.12.x` and older	Unsupported	`syn deploy` asks you to upgrade.

Pin the version in your pyproject.toml (for example synchronoid==0.14.2) so that local runs match your CI.

Shell completion

The CLI can print a completion script for Bash, Zsh and Fish.

terminal

# Bash
$ syn completion bash >> ~/.bashrc
# Zsh
$ syn completion zsh > "${fpath[1]}/_syn"
# Fish
$ syn completion fish > ~/.config/fish/completions/syn.fish

Restart your shell after you add the script.

Upgrading

Use the same tool you used to install.

terminal

$ pip install --upgrade synchronoid
$ pipx upgrade synchronoid
$ brew upgrade syn

Read the changelog first

Before 1.0, minor versions can change APIs. Read the changelog and run your tests with syn dev before you deploy an upgraded SDK.

Proxy settings

The CLI respects the standard HTTPS_PROXY and NO_PROXY environment variables. To trust a company certificate authority, set SYN_CA_BUNDLE.

terminal

$ export HTTPS_PROXY=http://proxy.internal:3128
$ export NO_PROXY=localhost,127.0.0.1
$ export SYN_CA_BUNDLE=/etc/ssl/certs/company-ca.pem
$ syn doctor

You can also store these values in the user config file at ~/.config/synchronoid/config.yaml. If installation succeeds but syn login fails, see Troubleshooting.

Next step

Continue with the Quickstart to create your first project.