CLI Reference

Complete reference for all synap subcommands, options, and outputs.

All commands accept an optional [PATH] argument (defaults to .) pointing to your Git repository root.

Setup & Initialization

`synap setup`

Interactive first-run wizard. Prompts for LLM provider, model, and stores API keys in the OS keyring.

synap setup .

`synap init`

Builds the SQLite AST graph from scratch. Runs Tree-sitter across all files, resolves dependency edges, and enqueues wiki jobs.

synap init .
synap init . --force         # Rebuild from scratch
synap init . --skip-wiki     # Skip async wiki generation
synap init . --skip-llm      # Structural-only (no LLM calls)

Output:

✓ Git root verified: /workspace/myrepo (branch: main)
✓ Tree-sitter parsers initialized (25+ grammars)
✓ Database schema created: .synap/synap.db (WAL mode)
› Indexing 1,120 files across 4 CPU cores...
✓ Indexed 8,421 symbols, 14,290 dependency edges
✓ Repository initialized at commit abc1234

Next Steps:
  synap start .      — Start the background daemon
  synap mcp config . — Get IDE connection config

Daemon Lifecycle

`synap start`

Launches the background daemon (detached). Starts the Git watcher and FastAPI diagnostics server.

synap start .

`synap stop`

Gracefully shuts down the daemon, releases PID and heartbeat lockfiles.

synap stop .

`synap restart`

Stop then start.

synap restart .

`synap status`

Shows indexing state, daemon health, and runtime metrics.

synap status .
synap status . --watch    # Live-refreshing dashboard
synap status . --json     # Machine-readable output

Live watch output:

  Daemon Status:   ACTIVE (PID 14455, Port 9876)
  Active Branch:   main | Commit: 40cba4b
  Indexed Files:   1,120 | Symbols: 8,421 | Edges: 14,290
  Wiki Pages:      14 Fresh, 0 Stale
  Avg Latency:     9.2ms

`synap run`

Run the daemon in the foreground (useful for debugging).

synap run .

Search & Query

`synap search`

Executes a hybrid structural + semantic query. Returns token-budgeted context.

synap search "AuthService" .
synap search "how does JWT verification work" . --max-tokens 3000

MCP Protocol

`synap mcp serve`

Starts the FastMCP stdio server in the foreground (used by IDE agents directly). synap mcp start is available as a direct alias.

synap mcp serve .
synap mcp start .   # Alias for serve

`synap mcp config`

Prints the exact JSON snippet to paste into your IDE's MCP settings.

synap mcp config .

`synap mcp verify`

Validates all MCP tool schemas and endpoint health.

synap mcp verify .

Indexing

`synap index`

Re-indexes all files explicitly (full re-parse, not incremental).

synap index .

`synap sync`

Incremental sync against recent Git commits (fast, delta-only).

synap sync .

Memory & Lessons

`synap checkpoint create`

Save agent state as a checkpoint on the current branch.

synap checkpoint create . --doing "Refactoring auth" --files "src/auth.py" --next-step "Run tests"

`synap checkpoint list`

List all checkpoints on the current branch.

synap checkpoint list .

`synap checkpoint restore`

View or restore a checkpoint.

synap checkpoint restore latest .

`synap lessons review`

Interactive TUI to review pending lessons awaiting approval.

synap lessons review .

`synap lessons approve <id>`

Approve a pending lesson to make it active.

synap lessons approve 1e2c345d-6789 .

`synap lessons reject <id>`

Reject and delete a lesson.

synap lessons reject 1e2c345d-6789 .

`synap memory status`

Count active, pending, and expired lessons.

synap memory status .

`synap memory prune`

Force-expire and remove stale lessons.

synap memory prune .

Wiki

`synap wiki list`

List all generated documentation files under .synap/wiki/.

synap wiki list .

`synap wiki show <filepath>`

Render a wiki page in the terminal.

synap wiki show src/auth/service.py .

Cost & Usage

`synap cost`

Show aggregated LLM token usage and estimated USD cost.

synap cost .

Output:

Provider: ollama | Model: qwen2.5-coder:14b
Calls: 48 | Input: 64,200 tok | Output: 12,400 tok
Estimated Cost: $0.0000 (100% local)

`synap usage show`

Alias for synap cost with a detailed per-call table.

synap usage show .

`synap usage clear`

Purge the LLM call log.

synap usage clear .

Maintenance

`synap doctor`

System health check: database integrity, Tree-sitter parsers, provider connectivity.

synap doctor .

`synap repair`

Repair a corrupted database file and rebuild the index.

synap repair .
synap repair . --yes   # Skip confirmation

`synap wipe`

Delete all local context data for a repository (.synap/ folder).

synap wipe .

`synap rollback`

Roll back the index to a previous Git commit state.

synap rollback . --commit abc1234 --yes

`synap logs`

View or stream daemon logs.

synap logs .
synap logs . --tail         # Stream in real-time
synap logs . --lines 50     # Last 50 lines
synap logs . --debug        # Include debug/trace output

`synap update`

Self-update Synapse to the latest PyPI version.

synap update

`synap uninstall`

Remove Synapse (auto-detects uv tool, pipx, or pip).

synap uninstall
synap uninstall --yes   # Skip confirmation prompt