Skip to Content
Getting startedStart with SynapseX CLI

Quickstart: SynapseX CLI

This page takes you from a clean machine to a real quantum simulation result in under two minutes, with no account and no network connection. Then it connects your SynapseX account so the same CLI can run AI models and open a terminal coding agent in your project.

Step 1: Install the SynapseX CLI

macOS and Linux:

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

This installs a single self-contained binary to /usr/local/bin/synapsex-code. If that directory is not writable, choose your own location:

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

Windows, in PowerShell:

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

The Windows installer writes to %LOCALAPPDATA%\synapsex-code and adds that directory to your user PATH.

Step 2: Verify the install

synapsex-code --version
1.17.9

One naming note, so nothing later confuses you: the command you type is synapsex-code, but the CLI’s own help output labels itself synapsexCode — that is the program’s internal script name, not a second command. There is no sx command.

Step 3: Run a quantum circuit with no account and no network

Save this file as bell.qasm:

OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;

Run it:

synapsex-code lab run bell.qasm --sim --shots 100 --seed 7

Observed output:

mode=sim (local, off-ledger, $0)  file=bell.qasm
qubits=2  shots=100
counts:
  11  57  (57.0%)
  00  43  (43.0%)

That is a real statevector simulation sampled 100 times. Only 00 and 11 occur — the two qubits are entangled. --seed 7 makes the sampling reproducible, so you can re-run the command and get the same counts.

What the local simulator actually supports

State these limits before you trust a result:

  • Gates: an OpenQASM 2.0 subset — h, x, z, s, cx. The OPENQASM, include, qreg, creg, measure and barrier lines are accepted and skipped.
  • Size: up to 24 qubits.
  • Shots: clamped to 1–4096, default 1024.
  • Unknown gates are silently ignored. They do not raise an error — the simulator treats them as a no-op and still prints counts. Check that your circuit uses only the supported gates, or the numbers you get will be for a different circuit than the one you wrote.

Step 4: Run any local file

The same command runs an ordinary file on your own machine, at no cost and with no ledger entry:

synapsex-code lab run hello.py --local
mode=local (off-ledger, $0)  file=hello.py
hello from lab local

Standard output and standard error are streamed through, and the command exits with the child process’s own exit code — so it drops straight into a script or a CI step.

Step 5: Connect your account for AI models

synapsex-code providers login

Choose SynapseX, enter your account email, and approve the code that opens at chat.synapsex.ai/activate in your browser. Nothing is pasted into your shell, so no long-lived secret ends up in your shell history.

Confirm the credential landed:

synapsex-code providers list
synapsex-code models

Step 6: Your first AI turn

One-shot, non-interactive — useful in scripts:

synapsex-code run -m synapsex/synapsex-atlas-7b-v1 "explain quantum superposition in two lines"

Or open the interactive terminal agent in the current project:

synapsex-code

How do I update the SynapseX CLI?

Re-run the install one-liner from Step 1. It replaces the binary in place.

Next steps

Start with SynapseX DesktopStart with the Platform API