CLI Reference

The synapses CLI is a single binary for project setup, indexing, daemon management, configuration, and diagnostics.

synapses <command> [flags]

Commands

synapses init

Set up a project: index the codebase, start the daemon, connect AI agents. This is the main entry point for new projects.

synapses init [--path <dir>] [--yes] [--agents <list>] [--no-agents]

synapses start

Start MCP server for a project. This is called by AI agents (via their MCP config), not directly by users.

synapses start [--path <dir>]

Internally, this starts the daemon if needed, registers the project, and bridges stdio to the daemon’s per-project Unix socket.

synapses stop

Stop the daemon.

synapses stop

No flags. Sends SIGTERM to the daemon process and waits for graceful shutdown.

synapses status

Full health check showing the state of every component, or list all indexed projects.

synapses status [--path <dir>] [--all]

Default output shows: App, CLI Binary, CLI in PATH, Global Config, Graph Index, Daemon, Brain, Doc Cache, Pulse.

synapses index

Build the code graph or reset cached indexes.

synapses index [--path <dir>] [--reindex] [--reset] [--all]

synapses config

Read or write configuration. Supports both global defaults (~/.synapses/config.json) and per-project overrides (synapses.json).

synapses config [--show] [--global] [--path <dir>] [key] [value]

Examples:

synapses config --show                          # Full merged config
synapses config --show brain.enabled            # Single key with source
synapses config --global brain.enabled true     # Set global default
synapses config brain.enabled false             # Set project override

Merge order: built-in defaults → ~/.synapses/config.json → <project>/synapses.json. Project always wins.

See Configuration Reference for all available config keys.

synapses connect

Write MCP configuration for an AI agent so it can use Synapses.

synapses connect [--agent <name>] [--path <dir>]

synapses update

Self-update the Synapses binary or rollback to the previous version.

synapses update [--check] [--rollback]

If running from the desktop app, updates are handled automatically by the app.

synapses remove

Remove Synapses from a project. The inverse of init. Cleans agent configs, project config, and cached index. Source code is never modified.

synapses remove [--path <dir>] [--yes] [--keep-data]

synapses uninstall

Remove Synapses from the entire system. Stops daemon, removes services, deletes ~/.synapses, removes the binary.

synapses uninstall [--yes] [--keep-data] [--keep-binary]

synapses version

Print the version.

synapses version

synapses completion

Generate shell completion scripts.

synapses completion <bash|zsh|fish>

Setup:

# Bash
eval "$(synapses completion bash)"

# Zsh
eval "$(synapses completion zsh)"

# Fish
synapses completion fish > ~/.config/fish/completions/synapses.fish

Subcommands

synapses dev

Developer tools for swapping the CLI binary (useful when building from source).

synapses dev <link|unlink|status>

State is stored in ~/.synapses/dev_link.json. When linked, the desktop app won’t overwrite your custom binary on updates.

synapses daemon

Low-level daemon control. Most users never need these — the daemon is auto-managed by synapses start.

synapses daemon <serve|install|uninstall|logs>