Skip to content

CLI Reference

Jump to bottom
Naveen Raj edited this page Apr 11, 2026 · 1 revision

CLI Reference

The synapse command manages the backend and frontend servers.

Prerequisites

Dependency Minimum Required
Python 3.11 Yes
Node.js 20.9.0 Yes
npm bundled with Node Yes
ollama any No (local models only)

Warnings are printed at startup if versions are below minimums. Missing ollama is non-fatal — cloud API models still work.

Installation

# Editable install (recommended for development)
python -m pip install -e .

# Or install normally
python -m pip install synapse-ai

# Run without installing
python -m synapse start

Run the interactive setup wizard before first start:

synapse setup

Environment Variables

Variable Default Description
SYNAPSE_DATA_DIR ~/.synapse/data Path to data directory
SYNAPSE_BACKEND_PORT 8765 Backend API server port
SYNAPSE_FRONTEND_PORT 3000 Frontend web UI port
SYNAPSE_PROFILING false Enable performance profiling (set by --profile)

Values in a .env file at the project root are loaded automatically. Environment variables already set are not overridden.

Commands

synapse start                                    # start backend + frontend, open browser
synapse start --detach                           # start in background (writes pidfiles)
synapse start --no-browser                       # start but don't open browser
synapse start --backend-port 8080 --frontend-port 4000   # custom ports
synapse start --profile                          # start with performance profiling

synapse stop                                     # stop background processes
synapse status                                   # show process status
synapse restart                                  # stop + start
synapse restart --detach --backend-port 8080    # restart detached on custom ports

synapse setup                                    # interactive setup wizard (API keys, settings)
synapse upgrade                                  # pull latest code and rebuild everything
synapse uninstall                                # remove Synapse (prompts for confirmation)
synapse uninstall --keep-data                   # uninstall but keep ~/.synapse data

Command Reference

start

Starts the backend and frontend. Waits for both to be ready, then opens the browser (unless --no-browser or --detach).

In foreground mode, Ctrl+C shuts down both processes cleanly. In detach mode, PIDs are written to the data directory.

Flag Default Description
--detach, -d off Run in background and write pidfiles
--no-browser off Do not open a browser on start
--backend-port PORT 8765 Port for the backend API server
--frontend-port PORT 3000 Port for the frontend web UI
--profile off Enable performance profiling

stop

Reads PID files and terminates both processes. Sends SIGTERM first, then SIGKILL if the process does not exit within 5 seconds. On Windows uses taskkill /F /T.

status

Prints whether the backend and frontend processes are running or have a stale PID.

restart

Equivalent to stop followed by start. Accepts the same port and detach flags as start.

Flag Default Description
--detach, -d off Leave processes detached after restart
--backend-port PORT 8765 Port for the backend API server
--frontend-port PORT 3000 Port for the frontend web UI

setup

Runs the interactive setup wizard. Prompts for API keys and settings and writes them to the project .env file.

upgrade

Pulls the latest code and rebuilds everything in place:

  1. Stops running services
  2. git pull --ff-only
  3. Recreates the backend virtual environment and reinstalls requirements
  4. Reinstalls synapse-ai in editable mode
  5. Runs npm install and npm run build in the frontend directory

uninstall

Permanently removes Synapse AI. Prompts for confirmation before proceeding.

Steps performed:

  1. Stops running services
  2. Removes startup registration (systemd on Linux, LaunchAgent on macOS, Registry on Windows)
  3. Removes data directory (~/.synapse/data) — skipped with --keep-data
  4. Removes installation directory (including backend/venv and frontend/node_modules)
  5. Runs pip uninstall -y synapse-ai
  6. Cleans PATH entries from shell config files
Flag Default Description
--keep-data off Preserve ~/.synapse data directory

PID Files

PID files are written to the data directory:

~/.synapse/data/backend.pid
~/.synapse/data/frontend.pid

Performance Profiling

The profile subcommand queries backend performance. Requires synapse start --profile.

synapse profile stats                  # per-endpoint latency (avg, p50, p95, p99, max)
synapse profile reset                  # clear collected timing stats

synapse profile cpu-start              # start CPU profiling
synapse profile cpu-report             # print CPU profile report
synapse profile cpu-report -o report.html  # save as HTML

synapse profile memory-start           # start memory profiling
synapse profile memory-snapshot        # snapshot current allocations (top 20)
synapse profile memory-snapshot --limit 50  # top 50

synapse profile spy                    # record py-spy flame graph (requires: pip install py-spy)
synapse profile spy -o profile.svg --duration 60

profile flags

Flag Default Description
--output FILE, -o — Output file (.html for cpu-report, .svg for spy)
--limit N 20 Top allocations to show (memory-snapshot)
--duration SECS 30 Recording duration in seconds (spy)

Quick Flow

python -m pip install -e .
synapse setup
synapse start --detach
synapse status
# ... use Synapse ...
synapse stop

Getting Started

Core Features

Integrations

Development

Clone this wiki locally