CLI Reference

The synapse command manages a self-hosted install — the backend and the frontend together — and drives a Synapse over its API: runs, schedules, chat and MCP.

synapse start          # start both, open a browser
synapse status         # are they running?
synapse logs           # what the backend said
synapse stop           # stop both
synapse upgrade        # install the newest release; added parts stay
synapse autostart on   # start when you log in
synapse --version      # which version this is

Running synapse with no arguments is the same as synapse start.

synapse --version prints the version and exits, from either entry point — the Python CLI and the npm wrapper. An installed SynapseOrch reports the installed package's version, and the npm launcher answers without installing anything; a source checkout reports the version in its pyproject.toml. Quote it in a bug report or a security report.

start

Starts the backend API and the frontend web UI, prints the address — with login off, the access link — and opens a browser on it:

Synapse is running → http://localhost:3000/?token=…
  Anyone with this link can use this Synapse. Share it only with people who may,
  or turn on login in Settings. `synapse access-link` prints it again.
Press Ctrl+C to stop.

The two servers' output goes to ~/.synapse/logs/backend.log and frontend.log — see logs. If one does not come up, start says which, with the last lines of its log. In a terminal, with nothing set up yet, it brings a 1.x install's data across, then runs setup only if something is still missing.

A port given here wins over the ports the installer or setup saved, which win over SYNAPSE_BACKEND_PORT and SYNAPSE_FRONTEND_PORT. See Environment variables.

synapse start -d --no-browser --backend-port 9000

stop

Stops both processes, found through the PID files start wrote. Nothing to pass.

status

Reports whether each process is running:

backend: running
frontend: running

A process that is not up reads not running, or stale pid 1234 when its PID file names a process that is gone. --json prints one line with the version, the home folder, each process, the address, whether the UI answers (ready), whether login is on, and the access link.

logs

Prints the last lines of a log — backend (the default), frontend or install, the installer's own.

The logs are in ~/.synapse/logs/, kept to three files of 10 MB each.

restart

Stops and starts. Takes --detach/-d, --backend-port, --frontend-port and --verbose, same as start; without -d it opens a browser.

autostart

synapse autostart on starts SynapseOrch in the background when you log in; off stops that; status prints on or off. It is the question the installer asks.

On WSL, or a Linux without a systemd user session, it says Start on login is not available here. The names are the ones 1.x used, so turning it on replaces a 1.x entry.

setup

Runs the setup wizard in the terminal: the default agent's name, the AI to use — provider, key and model — and the backend and frontend ports. start runs it by itself the first time, in a terminal, when nothing is set up yet.

synapse setup --apply - reads the settings as JSON on stdin instead, and writes only the keys it knows — what the installer uses.

synapse setup --knowledge-models fetches Docling's models for Knowledge's PDF reader into DOCLING_ARTIFACTS_PATH (about 670 MB, once; it says present when they are there). synapse upgrade --with knowledge runs it for you.

migrate

Creates or updates the database schema, and imports old 1.x data folders if any are present. The first boot does this automatically; run it by hand when you want the database prepared before the service starts, or to confirm an upgrade landed.

See Upgrading to 2.0.

upgrade

Installs the newest release over this one; your data and settings stay. It stops SynapseOrch, backs up the database to ~/.synapse/backups/, installs — with that release's own installer for a one-command install, with pip for a pip install — updates the database, and starts SynapseOrch again if it was running. It keeps the five newest backups. The optional parts installed stay installed.

An npm install is told to run npm install -g synapse-orch-ai@<version>, and a source checkout to git pull. On Windows the upgrade carries on in a new window.

uninstall

Stops SynapseOrch, removes its start-on-login entry, uninstalls the program and deletes ~/.synapse. It asks you to type yes first.

An npm install is removed with npm uninstall -g synapse-orch-ai. In a source checkout, uninstall refuses: delete the folder instead.

reset-password

Resets the UI login password. Use it when login is enabled and the password is lost — there is no recovery email on a self-hosted install.

access-link

Prints the link that opens Synapse while login is off — the access link start printed.

With login on, it says so instead: the link does not open Synapse while a password does.

api-keys

Manages keys for the external /api/v1 and /api/v2 surfaces.

synapse api-keys generate production   # create, and print the key once
synapse api-keys list                  # name, prefix, created, last used
synapse api-keys revoke <key-id>       # delete

The full key is shown only at generation. Afterwards only the prefix is stored, so there is nothing to recover — generate a new one.

These are unrelated to SYNAPSE_INTERNAL_TOKEN, which gates the UI's own routes.

Driving a Synapse

The rest of synapse does what an API key does, on this machine's Synapse, another install, or SynapseOrch Cloud: the v1 API's routes, and the MCP server's door for what has no route (building, deletes, Boards, what waits, activity and usage). On Cloud, building and deleting need a key made with Can also build. synapse --help lists the commands in sections and ends with where to start:

synapse workflows list                      # what there is to run
synapse run "Weekly report" -m "Q3 numbers"  # run one, and read its answer
synapse runs waiting                        # what waits on you, each with the command that answers it
synapse chat --agent "Research Agent"       # talk to an agent

Each command's --help has examples.

Running and answering. run <workflow> starts a run and follows it to the end: -m/--message is what to work on, -i KEY=VALUE (repeatable; JSON when the value is JSON) and --input-file FILE (a JSON object; - reads stdin) set its inputs, --detach prints the run id and leaves it running, and --webhook URL (with --webhook-secret to sign it) posts the outcome there when the run ends — through the v2 API, which a self-hosted install serves in scale mode. runs answer <run_id> answers a paused run — the text, or --field NAME=VALUE for each field, or --approve / --reject (with --reason) for a tool call it asks about; --question picks one of a team's several questions by its id. chat --session ID --approve (or --reject) allows or refuses the call a conversation stopped on.

Which Synapse, and which key. The target is --url, else SYNAPSE_API_URL, else this machine's backend. It is an origin — https://api.synapseorch.com, say — and the CLI adds the API's path. The key is --api-key, else SYNAPSE_API_KEY, else a key the CLI keeps for that origin (synapse login --url ORIGIN --api-key-stdin keeps one; logout --url ORIGIN forgets it). This machine's Synapse needs no key: the CLI makes one of its own the first time, named Synapse CLI so it is plain in Settings → API keys why it is there, and keeps it in ~/.synapse/cli.json (readable by you only). Revoking it is safe; the next command makes another. synapse target says which Synapse and key a command would use, and whether it answers.

With this machine's login turned on, the CLI asks for it too: run synapse login first. The session lasts 7 days, as the browser's does.

Deletes ask first. A delete shows what it would remove and asks y/N; --yes skips the question, and a script without --yes is refused rather than left waiting. A delete is refused while something still uses the thing.

For scripts. Results go to stdout and messages to stderr. --json prints JSON — one document, or one event a line for a run — and an error as one JSON object on stderr; lists take -q for ids only. A dropped stream is read on from where it stopped. The exit code says how it ended:

Every door. synapse tools call NAME --arg key=value calls any product tool a key is offered, and synapse api METHOD PATH (with -d for a body, -F for a field, --stream for a stream) any route a key reaches, as gh api does.

profile

Performance profiling of the running backend. Useful when a workload is slower than it should be and you want to know where the time goes.

synapse profile <action> [--output FILE] [--limit N] [--duration SECS]

Latency stats need the backend started with --profile, or SYNAPSE_PROFILING=true.

synapse start -d --profile
# ... exercise the slow path ...
synapse profile stats
synapse profile spy --duration 60 --output flame.svg

Where things live

An installed SynapseOrch — the one-command install, npm or pip — keeps everything in one folder, ~/.synapse (%USERPROFILE%\.synapse on Windows). SYNAPSE_HOME moves it.

cli.json and chat_history stay in ~/.synapse even when SYNAPSE_HOME points elsewhere. The program itself is a uv tool, outside this folder.

A source checkout keeps its data and PID files in backend/var/ and its .env at the repository root. Paths for the data are configurable — see Environment variables.