CLI command reference

This page is the complete list of commands and flags in the shipped SynapseX CLI (synapsex-code, version 1.17.9). Use it to look up an exact flag name, its default and what it does, so you can write a working command on the first try instead of guessing.

New to the CLI? Install it first at /cli/install, then come back here for the exhaustive list.

Why you cannot discover these flags with --help

synapsex-code --help and one-level help such as synapsex-code run --help work. Help at sub-subcommand depth does not. Running synapsex-code lab run --help, synapsex-code mcp add --help or synapsex-code agent create --help prints the top-level help instead of the subcommand’s own help. That is a defect in the shipped binary.

This page is therefore the authoritative flag list for lab, mcp and the other nested command groups. Do not try to discover those flags from the terminal.

Which commands exist

These are the top-level commands registered by the binary, in registration order:

completion, acp, mcp, the default TUI command ([project]), attach, run, generate, debug, a hidden console group, providers, agent, upgrade, uninstall, serve, web, models, stats, export, import, github, gitlab, pr, session, lab, plugin, db.

Not documented here — do not use:

Global flags

These work on every command.

Each of the three has an environment-variable equivalent — see /reference/cli-configuration.

Terminal agent: the default command and run

synapsex-code [project] opens the interactive terminal agent in the current directory (or in project if you pass a path). synapsex-code run [message..] does a single non-interactive turn, which is what you want in scripts and CI.

# Interactive agent in the current project
synapsex-code
 
# One-shot turn
synapsex-code run -m synapsex/synapsex-atlas-7b-v1 "explain quantum superposition in two lines"

run also accepts --port, -u and -p from the network table below when you point it at a server with --attach.

providers — sign in and manage credentials

The group is also aliased auth. There is no separate top-level auth command.

Only two provider ids are accepted: synapsex (AI models) and synapsex-compute (SynapseX Compute). Third-party providers are rejected — providers login --provider anthropic fails with Unknown provider "anthropic". Full sign-in walkthrough: /cli/authentication.

models — list model ids

synapsex-code models

The CLI writes model ids as synapsex/<id>. See /reference/models for how ids are written on each surface.

lab — local runs and SynapseX Compute

Two lab capabilities work offline, with no account and no credits: lab run --local and lab run --sim. Everything else in this group requires SynapseX Compute access, which is not generally available today — those commands exist in the binary and reach live endpoints, but they are gated and their signed-in behaviour is not something these docs can promise.

# Free local OpenQASM simulator, no account required
synapsex-code lab run bell.qasm --sim --shots 100 --seed 7

Flags for lab run:

Flags for lab ask:

Simulator limits you must know. The local simulator supports only the gates h, x, z, s and cx. OPENQASM, include, qreg, creg, measure and barrier lines are skipped. Any gate it does not recognise is silently ignored — no error, no warning. A circuit using unsupported gates will still print counts, and those counts will be wrong. Treat --sim as a fast diagnostic probe, not a transpiler. Details: /cli/quantum-simulator.

lab run --local picks the interpreter from the file extension: .py uses the interpreter in SYNAPSEX_PYTHON (default python3); .js, .mjs, .cjs and .ts use node; .sh and .bash use sh; .rb uses ruby; .pl uses perl; a file with no extension is executed directly. Anything else returns an explicit unsupported-extension error. See /cli/local-runs.

serve, web, attach, acp — network commands

With no password set, serve and web print Warning: SYNAPSEX_CODE_SERVER_PASSWORD is not set; server is unsecured. and start anyway. Set a password before binding to anything other than loopback. See /cli/headless-server.

mcp — Model Context Protocol servers

Exactly one of --url or a command after -- is required; supplying neither fails with Provide either --url <url> or a command after --. Guide: /cli/mcp-servers.

agent and session

stats, export, import, db

More detail: /cli/sessions-and-usage.

plugin, completion, uninstall, debug

synapsex-code debug exposes these subcommands:

debug paths and debug config are the fastest way to see exactly which files your machine is reading — see /reference/cli-configuration.