Synap CLI Reference

The synap command-line interface for the personal intelligence substrate. Every command listed here is reflected directly from the installed CLI's --help output — this page regenerates from source on each CLI release.

Version: 1.1.0 · Generated 2026-05-28

Install

curl -fsSL install.synap.ing | sh

Installs synap and synap-mcp to ~/.local/bin/.

Self-update

synap upgrade

Command reference

Setup

Command	Description
synap onboard	First-run welcome — 4 paths to fill your empty graph (capture / wire AI / import / explore). Print-mode version of the TUI's empty-Thoughts hub.
synap wire [-y] [--tool=X]	Detect AI tools on this machine and wire each one (MCP server + cognition-layer instructions). Guided path for new users — preview + confirm before any writes. Re-runnable; idempotent.
synap setup [--dry-run]	Power-user variant of wire (no preview/prompt; just runs full install across all detected tools).
synap login [email]	Log in to synap.ing
synap logout	Clear stored credentials
synap register [name]	Create new account
synap whoami	Show current identity
synap profile [name]	Show/switch profiles
synap mcp	Start MCP server (stdio)
synap upgrade [-y]	Update synap CLI to the latest published version (--force re-installs same version; --channel=latest)
synap tui	Full-screen TUI: thoughts / search / capture / soul / stats / timeline / playground / schema / verify / graph / tags / api-tail / mcp-tap / mesh
synap import [kind] [path]	Bulk-import existing notes. Kinds: obsidian (preserves [[wikilinks]] as edges) / markdown (generic) / chatgpt (v1.0.5+). DRY-RUN by default; pass --commit to write. Example: synap import obsidian ~/Vault --commit
synap ingest [text|stdin]	CANONICAL entrypoint for any "anything → graph" flow. --source X --type Y --tag T --tags a,b --project P --commissure ID --scope INSIGHT,DECISION. The shape every SDK will mirror. Example: gh pr view 42 | synap ingest --source gh --tag DECISION
synap exec [cmd...]	Run a shell command, capture stdout + exit as a thought ([EXEC] prefix). --tag X overrides, --no-save skips capture. Example: synap exec -- npm test
synap pipe	Read stdin, save as a thought ([PIPE] prefix). Quick variant of 'ingest'. Example: cat notes.md | synap pipe --tag RESEARCH
synap recipes [name]	Built-in integration cookbook (gh, kubectl, git, ci, observability, ai, slack, browser). Example: synap recipes show gh capture of recent commands via synap-capture-last
synap tail [query]	Tail -f for your knowledge graph — new matches print live every --interval seconds (default 5). Example: synap tail "[DECISION]" --interval 3
synap demo	Launch TUI in READONLY mode (writes blocked). Safe for screens-shared demos. Equivalent to: SYNAP_READONLY=1 synap tui
synap play [file]	Replay a .synrec recording (made via ':rec start' / ':rec stop' inside the TUI). --speed N, --readonly.

Thoughts

Command	Description
synap list [n]	List recent thoughts (default 15)
synap add [content]	Add a thought (auto-detects [TAG] prefix)
synap get [id]	Get thought by ID
synap delete [id]	Delete a thought

Search

Command	Description
synap search [query]	Keyword search (BM25)
synap similar [query]	Semantic search (hybrid)

Graph

Command	Description
synap link [from] [to] [type]	Create edge (intentional) Find candidates to link [id] to. Server returns top-k similar thoughts + their existing edges; you (or your AI) decide which deserve a link.
synap edges [id]	List edges for thought
synap orphans [n]	Find unconnected thoughts
synap traverse [id] [depth]	Walk graph from node
synap path [from] [to]	Find shortest path
synap reason [query]	Assemble reasoning context from graph
synap stats	Graph statistics
synap scored [n]	Thoughts ranked by relevance

Maintenance

Command	Description
synap dedup [threshold]	Find near-duplicates
synap link-orphans [threshold]	Auto-connect orphans
synap export [n]	Export as MAAP bundle
synap soul	Render full identity profile

System

Command	Description
synap status	Server health Pre-flight check: MCP, server, auth, soul, graph, bootstrap file, and per-harness MCP wiring. Exit codes: 0=pass, 1=fail, 2=warn (or 1 with --strict). Install / remove the once-per-day shell hook that runs synap doctor --quiet and warns on drift. --with-auto-upgrade adds a weekly synap upgrade -y hook for hands-free updates (opt-in, removable with --no-auto-upgrade).
synap usage [days]	Usage statistics
synap keys [create|delete]	Manage API keys
synap sessions [n]	List midbrain sessions
synap mesh	Same as 'mesh status' — full per-peer status view
synap tap	Same as 'tap status'
synap SYNAP_MCP_TAP=redact	Log tool name + arg KEYS only (default — safe to share)
synap SYNAP_MCP_TAP=full	Log full arg values (sensitive — debug only)
synap SYNAP_MCP_TAP=off	Disable logging entirely

Options

Command	Description
synap --project [name]	Filter by project
synap --url [url]	Override server URL

Usage example

# capture a thought
synap ingest "AI tools forget you between sessions; substrate keeps you intact"

# search what you've captured
synap similar "AI memory continuity"

# wire AI tools to your graph
synap wire

See also

• Install — get the CLI on your machine
• iOS App — capture from anywhere
• Build on Synap — API access for SDK consumers