CLI reference

Open the native desktop application. Running synapse

Run the MCP stdio server until the client closes the connection. The process holds a shared database lifecycle lock.

Resolve global, project, and folder vault mappings for the current directory, refuse on any scope warning, read the selected values out of the vault, and launch the child. Synapse returns the child exit code, or 1 when the operating system reports no code.

Start a coding tool with Synapse already in place: memory and the vault reachable over MCP, this folder's vault variables in its environment, and the project root it should treat as home. Everything after a bare -- is passed to the tool untouched. A tool Synapse is not connected to is wired for the life of the process, so this works before setup has ever run and writes nothing into the tool's own configuration. Options: --directory, --model, --allow-tool (repeatable), --strict, --no-vault, --skip-permissions, --as <name> with --role, --task, and --channel to join the mesh as well, and --print to show the resolved command and environment names without running anything. Refuses on any scope warning, and never prints a secret value.

Show the resolved folder, available environment names, discovered scope states, warnings, ambient readiness, and detected shell hook. Reports which value store this machine uses and never a value. The folder defaults to the current directory.

Print the integration script for a shell. Evaluate or source it from that shell’s startup file. The hook reevaluates approved directory scopes after directory changes and before prompts.

Inspect and approve the exact contents of the closest .synapse.yaml at or above the folder. The folder defaults to the current directory.

Revoke approval for the closest discovered scope. An installed hook unloads its managed values at the next prompt or directory change.

Internal hook protocol. Emits a shell-quoted environment diff that the installed hook evaluates. Users normally invoke hook, allow, and deny instead.

List vault names alphabetically.

Create a unique vault. Names may contain ASCII letters, numbers, and hyphens.

Delete an empty vault. Forget every contained secret first.

Print which store holds this machine's secret values, or choose one. Choosing moves nothing, so it refuses once secrets exist and points at vault migrate. The encrypted store is the default on a new installation and the only one off macOS.

Move every value into the other store: copy them all, read each one back, switch the setting, then remove the originals. --keep leaves the originals in place. A source that cannot be read stops the migration with nothing moved and nothing switched.

List each vault.name reference, environment name, and whether it is global or scoped. Never prints a value.

Read a value from a hidden terminal prompt or stdin and save it in the vault. Creates metadata when the label is new; replaces the stored value when the environment name matches. --global also enables the mapping.

Put one value on the clipboard. The only way a stored value comes back out, and it never reaches the terminal: the command prints the reference and nothing else. Set SYNAPSE_CLIPBOARD to use something other than pbcopy.

Delete the stored value, its metadata, and any global mapping. The value is removed from both stores, so a machine that has switched backends leaves nothing behind in the one it stopped reading.

Enable or disable a secret’s global environment mapping. Enabling replaces the current global source for that environment name.

Create a new .synapse.yaml. The folder defaults to the current directory. Use --folder for a folder-kind template; the command refuses when the file already exists.

Approve an exact scope path directly by parsing it, calculating its content digest, and storing that digest with its canonical path. synapse allow is the directory-oriented shortcut.

Alias the scope-oriented status flow to the same resolved output as synapse status.

Search the body with the joined query words or list recent memory when empty. Returns up to 100 entries. Text mode prints ID, scope, source, and a compact preview, and marks any memory that has been superseded. With --explain, print what the search actually did first: the full-text expression the query became, the words it searched for, the words it dropped for matching nearly everything, and the score behind each hit.

Find memories containing an exact string, most recent first. Nothing is tokenized, ranked, or dropped — the characters given have to appear, in that order — which is what makes it the right tool for an identifier, a flag, a path, or a word the ranked search treats as noise. Matching is case-insensitive for ASCII, and a pattern after a bare -- is taken literally, so memory grep -- --no-verify searches for the flag.

Print one exact memory with scope, project root, source, and timestamp, or return structured JSON.

Read a non-empty body from stdin. Project scope is the default and resolves from the current folder; use global only for context that belongs everywhere.

Read the replacement body from stdin and replace one existing memory. The optional source replaces the source label.

Stop recalling one memory in favour of another. The old one is not deleted: it keeps its id, stays listed and readable, says what replaced it, and comes back with memory restore. Use this instead of leaving a correction to argue with what it corrects.

Put a superseded memory back in circulation. Deleting the memory that replaced it does the same thing on its own.

Preview recognized durable memory without changing its source. Add --confirm to import safe entries. Credential-shaped entries remain flagged unless the CLI also receives --include-flagged after source review.

List import batches, their provider, stored and linked counts, and whether each batch is active or undone.

Remove memories created only by that import batch. Preserve manually edited memories and records linked to another origin.

Delete one memory. The exact --confirm guard is required.

Delete every memory entry and import batch while leaving SOUL.md, settings, vaults, stored values, and scope approvals intact. The exact guard is required.

Show whether the mesh is on, how many agents are reachable, and how many background workers are running.

List every agent with its role, reachability, last reported work state, and the project it is working in.

List the channels in use and how many agents subscribe to each.

Print the messages agents have sent each other. With --follow the command keeps printing new ones until interrupted.

Open one agent in this terminal, wired into the mesh with a role. Options: --role, --tool claude|codex|pi, --task, --channel (repeatable), --allow-tool (repeatable), --model, --directory, --lead, --optimize, --strict, --skip-permissions, --command <template>, and --print to show the resolved command without running it.

Open a whole roster. The first member runs in this terminal as the lead; the rest run in the background and stop when the lead closes.

Join the mesh as yourself and drive a team from one terminal. You get a name on the roster and the same messaging every agent has, so you can address any agent directly instead of relaying through a lead — and an agent that gets stuck can ask you. With --team the whole roster starts in the background with you as the lead. Type @name text for one agent, #channel text for a channel, !text for everyone, or a bare line to whoever is focused. /help lists the commands; /quit leaves and stops the workers it started. The name defaults to your login name.

Manage reusable agent roles. Create, edit, and delete write into the project by default, or into your own layer with --user. Editing a built-in copies it down first, and a file that does not parse is never saved.

Manage team rosters, resolved and edited exactly like roles.

List background workers with their state, process id, and log path.

Stop a background worker. A worker owned by a Synapse session that is still running has to be stopped from there.

Report this session's Synapse connection as Claude Code session-hook output. Synapse installs this for you when you connect Claude Code; run it by hand to see exactly what a session will be told. Reads the calling tool's JSON on stdin.

Answer a tool's pre-compaction hook. Asks the session to write down anything durable it settled before its context is compressed away, and recalls nothing — the window is being reclaimed. Synapse installs this for you when you connect Claude Code. Never blocks or rewrites the compaction. Reads the calling tool's JSON on stdin.

Print one status line for a connected tool, reading that tool's JSON on stdin.

List the library with each skill's file count and description. A skill whose SKILL.md does not parse is reported on stderr and skipped.

Print one skill's SKILL.md.

Start a skill from a template. Names follow the standard: lowercase letters, digits, and single inner hyphens.

Open a skill in $VISUAL or $EDITOR. A draft that does not parse is never saved over the working one.

Remove a skill from the library. Copies already installed in tools are left alone.

Copy the library into your tools. Without a name it installs everything; without --tool it installs into every connected tool. A copy that was edited in place, or a skill Synapse never wrote, is refused unless --replace is given.

Take a skill back out of a tool. Only a copy Synapse installed and nobody has changed is removed; --force overrides that.

Show where each skill stands in each tool, and any skill a tool has that the library does not.

Copy a skill a tool already has into the library and record that tool as having it, so it stops reading as unmanaged.

List the skills agents have written that nobody has looked at yet, oldest first, with the tool that wrote each one and the line it left saying why. A proposed skill is in the library and in no tool.

Install a proposed skill where it belongs and stop calling it proposed. A global skill goes into every connected tool's personal skills folder; a project skill goes into that project's.

Turn a proposed skill down. It leaves the library with its history, and nothing else on the machine ever knew about it. Only a skill still waiting for review can be rejected — once one is approved it is an ordinary skill, and skill delete is what removes it.

Show what a skill used to say, newest first, with the line saying what was wrong with each version. The newest twenty are kept.

Put an earlier version back, in the library and in every tool holding a copy Synapse wrote. What it said is kept as a new revision, so a revert can itself be reverted.

Open the database, run page and foreign-key integrity checks, apply supported migrations, and report the path, schema version, and ok integrity state.

Create and validate a consistent SQLite snapshot of brain.db at a destination that does not already exist. Secret values live in a separate store — Keychain, or vault.db beside it — and are never in the snapshot.

Validate a current-version snapshot and restore it while the app and MCP servers are closed. Preserves the previous database as a recovery backup and refuses without the exclusive lock.

Print the active recall optimization, result limit, character budget, supported shell modes, and zsh hook example.

Change the shared MCP recall response budget. Stored memory is not modified.

Turn the agent mesh tools on or off. Connected tools pick the change up the next time they start.

The most background workers one session may run at once. Every worker is a separate session on the account you already pay for, so this is a spending limit as much as a performance one. Clamped to a built-in ceiling, so a mistyped number cannot buy an unbounded fleet. A supervisor already running picks the change up on its next spawn.

Draw the reactor in the middle of the app's console, or leave the column to the numbers beside it. Nothing is lost by turning it off. A build made without the reactor feature has none to draw whatever this says.

Let agents write and correct skills, adding teach and revise to every connected session. Off by default. A skill an agent writes waits in skill proposed until you approve it, so turning this on never changes how a session behaves without you having read what changed it.

Print the SOUL.md path, whether it exists, pointer coverage, and whether both global instruction files are pointer-only.

Create SOUL.md when needed and refresh managed pointers in both global instruction files without removing unmanaged text.

Move unmanaged global guidance into SOUL.md, replace both global files with managed pointers, and retain backups.

Every tool this machine can connect to, with the layer each one resolves from.

Print one descriptor and where it came from.

Describe a tool Synapse does not ship. Opens a commented template in your editor and refuses to save a file that would not load. The name becomes the descriptor's file name and what you pass to --tool.

Edit a descriptor. Editing one Synapse ships copies it into a layer you own first, so the shipped file stays as it was.

Remove a descriptor you added. Deleting a copy that overrides a built-in returns you to the shipped one.

Install the current executable for this user. A packaged app creates a launcher into the signed bundle; a development binary is copied atomically. Unrelated destination files are never overwritten.

Print the resolved data directory, SOUL.md, and CLI destination.

Report everything a bug report needs: version, store state and size, connected tools and what each is set up with, skill and mesh state, shell and CLI integration, resolved paths, and recent crashes. Every check reports rather than fails, so a broken store is described instead of stopping the report. Nothing is sent anywhere.

Wire a tool into memory and the vault: register the Synapse MCP server through that tool's own CLI, and point its global instruction file at SOUL.md. With no name it connects every tool this machine has. Synapse never edits a tool's configuration itself — it asks the tool to.

Undo one tool's connection, or every tool's when no name is given: the MCP registration or installed package, the managed block in its instruction file, the Claude Code hooks and status line, and any skill Synapse installed for it. A skill you wrote, or a status line somebody else configured, is left alone.

Remove everything Synapse installed: every tool connection, the shell hook, and the command line tool. Without --confirm it prints what it would remove and stops. Your memory is left alone unless you also pass --data, which cannot be undone.

Print the application version. --version and -V are aliases.

Print the command summary. --help and -h are aliases at the top level.