Install and update the SynapseX CLI

This page gets the synapsex-code binary onto your machine and proves it works. At the end you will have a working CLI, a version number you can quote in a bug report, and a smoke test that passes without any account or network access.

Nothing needs to be built. The installer downloads a single self-contained binary — no Node, no bun, no Docker, no repository checkout.

Install on macOS and Linux


curl -fsSL https://synapsex.ai/install.sh | sh

This installs the binary as synapsex-code into /usr/local/bin.

If /usr/local/bin is not writable, choose another directory:


curl -fsSL https://synapsex.ai/install.sh | INSTALL_DIR=$HOME/.local/bin sh

When you override INSTALL_DIR, make sure that directory is on your PATH. Otherwise the install succeeds and the synapsex-code command is still not found.

Install on Windows

In PowerShell:


irm https://synapsex.ai/install.ps1 | iex

This installs to %LOCALAPPDATA%\synapsex-code and appends that directory to your user PATH. Open a new terminal afterwards — an already-running shell does not pick up the new PATH.

Verify the install


synapsex-code --version

At the time of writing this prints 1.17.9.

For a fuller picture — version, operating system, terminal and loaded plugins:


synapsex-code debug info

Smoke test with no account

None of these commands need credentials or a network connection, so they are a clean way to confirm the binary is healthy before you sign in.


synapsex-code models        # empty until you sign in — that is expected
synapsex-code agent list    # shows the built-in `build` agent
synapsex-code debug paths   # prints the resolved data, config, cache and state paths

synapsex-code models printing nothing is the correct behaviour without credentials: the model catalog only loads once a provider is configured. See Sign the CLI in to your SynapseX account.

For a first result you can actually see, run the offline quantum simulator: Run a quantum circuit offline with the CLI.

How do I update the SynapseX CLI?

Re-run the same install one-liner. That is the supported update path.


# macOS / Linux
curl -fsSL https://synapsex.ai/install.sh | sh


# Windows PowerShell
irm https://synapsex.ai/install.ps1 | iex

Setting a VERSION variable does not pin a version — the download URL contains no version component, so the installer always fetches the current build.

How do I uninstall the SynapseX CLI?


synapsex-code uninstall

Flag	Effect
`-c`, `--keep-config`	Keep configuration files
`-d`, `--keep-data`	Keep session data and snapshots
`--dry-run`	Show what would be removed, without removing it
`-f`, `--force`	Skip confirmation prompts

All four default to false. Run it with --dry-run first if you want to see the file list before anything is deleted.

A note on `--help`

Top-level help works: synapsex-code --help, and one level down such as synapsex-code run --help.

Help at the sub-subcommand level does not. synapsex-code lab run --help, synapsex-code mcp add --help and similar print the top-level help instead of the command’s own flags. Use CLI commands on this site as the flag reference for those commands.

Next step

Sign the CLI in to your SynapseX account.