CLI Commands
The synapse CLI manages the backend and frontend processes, handles upgrades, and provides status reporting. It is installed automatically by the setup script and added to your PATH.
synapse start
Starts the backend API server and the frontend UI, then opens the browser.
synapse start
Both processes run in the background. Logs are written to ~/.synapse/logs/.
Options:
| Flag | Description |
|---|---|
--no-browser | Start services without opening the browser |
--backend-only | Start only the FastAPI backend |
--frontend-only | Start only the Next.js frontend |
synapse stop
Stops both the backend and frontend processes.
synapse stop
synapse status
Shows whether the backend and frontend are running, and on which ports.
synapse status
Example output:
Backend ✓ running on http://localhost:8000
Frontend ✓ running on http://localhost:3000
synapse upgrade
Pulls the latest version from GitHub, reinstalls Python and Node.js dependencies, and restarts the services.
synapse upgrade
Your data (agents, orchestrations, vault, settings) is preserved in the data directory and is untouched by upgrades.
synapse uninstall
Stops all services and removes ~/.synapse (the data directory). The repo folder is left intact.
synapse uninstall
This deletes your agents, orchestrations, vault files, settings, and logs. Make sure to export anything you want to keep before uninstalling.
Environment variables for CLI
The CLI respects the following environment variables (or .env in the repo root):
| Variable | Default | Description |
|---|---|---|
SYNAPSE_DATA_DIR | backend/data | Where to store user data |
SYNAPSE_BACKEND_PORT | 8000 | Backend API port |
SYNAPSE_FRONTEND_PORT | 3000 | Frontend UI port |
OLLAMA_BASE_URL | http://127.0.0.1:11434 | Ollama server URL |
Setup wizard
The setup wizard runs automatically on first install. To re-run it manually:
cd /path/to/synapse-ai
python3 setup.py
The wizard asks you to choose a LLM provider, set API keys, configure ports, and optionally enable the login system.