Skip to main content

Install the Synth CLI

The Synth CLI is the supported command-line client for searching and reading evidence from a remote Synth deployment. The PyPI package is synthkb-cli; the command it installs is synth.

Requirements​

  • Python 3.11 or newer
  • macOS, Linux, or Windows
  • HTTPS access to your Synth deployment
  • A Synth API key with knowledge:read

Check your Python version before installing:

python3 --version

On Windows, use the Python launcher:

py --version

If the version is older than 3.11, install a current Python release first. The CLI is tested with Python 3.11 through 3.14.

pipx installs command-line applications in isolated Python environments while making their commands available in your shell. This avoids dependency conflicts with system Python and other Python applications.

macOS​

Install pipx with Homebrew, then install Synth CLI:

brew install pipx
pipx ensurepath
pipx install synthkb-cli

Open a new terminal after pipx ensurepath if your shell asks you to.

Linux​

Install pipx with your distribution package manager when available. The portable Python installation is:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install synthkb-cli

Open a new terminal after updating PATH.

Windows​

In PowerShell:

py -m pip install --user pipx
py -m pipx ensurepath
pipx install synthkb-cli

Close and reopen PowerShell after ensurepath.

If more than one Python version is installed, select a compatible interpreter explicitly. For example, on macOS or Linux:

pipx install --python python3.13 synthkb-cli

Alternative: install with uv​

If you already use uv, install Synth CLI as an isolated tool:

uv tool install synthkb-cli

If the command is not immediately available, run:

uv tool update-shell

Then open a new terminal.

Alternative: install with pip​

Regular pip works when it uses Python 3.11 or newer. Use a virtual environment instead of modifying the operating system's Python installation:

python3 -m venv ~/.venvs/synth
source ~/.venvs/synth/bin/activate
python -m pip install --upgrade pip
python -m pip install synthkb-cli

On Windows PowerShell:

py -m venv $HOME\.venvs\synth
& $HOME\.venvs\synth\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install synthkb-cli

The virtual environment must be active whenever you run synth. For a globally available CLI command, prefer pipx or uv.

Verify the installation​

synth --version
synth --help

The version command should print a release such as:

synth, version 0.5.0

Confirm the executable selected by your shell when troubleshooting:

command -v synth

On Windows:

Get-Command synth

Connect to Synth​

Create an API key with knowledge:read in Global Settings → API Keys or Settings → Connect, then run:

synth login https://synth.example.com
synth projects
synth use PROJECT_NAME
synth search "authentication refresh"

The interactive login prompt does not echo the key. The CLI stores credentials in the operating-system keychain when available.

If the public Synth URL is protected by Cloudflare Access or another Zero Trust gateway, continue with CLI Access Gateways to configure the required headers without changing Synth-specific authentication.

Upgrade​

With pipx:

pipx upgrade synthkb-cli

With uv:

uv tool upgrade synthkb-cli

To install an approved version exactly:

pipx install --force 'synthkb-cli==0.5.0'
# or
uv tool install --force 'synthkb-cli==0.5.0'

Uninstall​

Remove the saved local credential first when this workstation should no longer connect to Synth:

synth logout

Then remove the tool:

pipx uninstall synthkb-cli
# or
uv tool uninstall synthkb-cli

Uninstalling the package does not silently delete configuration or revoke the server-side API key. Revoke the key in Synth settings when its access must end.

Troubleshooting​

SymptomResolution
Requires-Python >=3.11Your selected Python is too old. Install Python 3.11+ or pass a compatible interpreter to pipx.
No matching distribution found after a Python-version warningPyPI found the release but rejected it for the selected Python. Upgrade Python.
synth: command not foundRun pipx ensurepath or uv tool update-shell, then open a new terminal.
externally-managed-environmentDo not modify system Python. Use pipx, uv, or a virtual environment.
The wrong synth runsCheck command -v synth or Get-Command synth, remove the older installation, and open a new terminal.

Continue with the Synth CLI reference for commands, authentication, deterministic reads, diagnostics, and exit codes.