CLI
Every command of @synap-core/cli, generated from its command definitions.
Generated from Synap-core/synap-cli@7562355c1 (main): docs/reference/cli.json. Do not edit this page; see scripts/generate-reference.mjs.
@synap-core/cli (command synap) connects computers and AI agents to a pod and works with the pod from a terminal.
It needs Node.js 20 or later.
npm install -g @synap-core/cli # or run it once with: npx @synap-core/cli <command>
synap --help
synap <command> --help--pod <name> works on every command: it runs that one command against a saved pod profile instead of the active
pod.
Files and environment
| File | Contents |
|---|---|
~/.synap/credentials.json | Your Synap account token. |
~/.synap/config.json | Saved pods: URL, workspace, agent identity and key. (Older versions used pod-config.json.) |
Never commit them.
| Variable | Default |
|---|---|
SYNAP_CP_URL | https://api.synap.live |
SYNAP_LANDING_URL | https://synap.live |
Commands
220 commands, grouped by top-level command. 5 hidden commands (internal or deprecated) are not listed.
| Global option | Description |
|---|---|
-V, --version | output the version number |
--pod <name> | Run this command against a saved pod profile (overrides the default pod for this invocation only) |
synap init
Full setup: connect to a Synap pod and install the skill
synap init [options]| Option | Description |
|---|---|
--pod-url <url> | Synap pod URL (skip pod choice prompt) |
--api-key <key> | Hub Protocol API key (skip key generation) |
-y, --yes | Accept the defaults, no prompts (connects the agents found on this machine) |
--agents <list> | Agents to connect, comma-separated: claude-code,codex,cursor |
--json | Print a JSON summary on stdout: {podUrl, connected, notApproved, failed, pairLink, exitCode} |
Exit codes:
0 at least one agent connected
2 not a terminal, or a bad flag (pass --pod-url and --agents)
3 no pod found, created or reachable
4 cancelled
5 could not get your key for the pod (pass --api-key)
6 the pod is ready but no agent was connectedsynap launch
Stand up a NEW company/OS on a pod — creates a project + its core workspaces (interactive)
synap launch [options]| Option | Description |
|---|---|
--list | List what can be launched (local templates, no pod needed) and exit |
--search <query> | Filter --list by name/description/slug |
--type <type> | Filter --list by package type (workspace|capability|skill|workflow|view|cell) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap connect
Plug something into your pod: an AI agent (claude-code, cursor, codex, …) or a tool/account (gmail, github, …)
synap connect [options] [thing]| Option | Description |
|---|---|
--tool | Treat <thing> as a tool/account even if it is also an agent name (no <thing>: list connectable services) |
--workspace <id> | Focus on one workspace (default: pod-wide) |
--project <id> | Focus on one project (agents only; composable with --workspace) |
--pod-url <url> | Synap pod URL |
--api-key <key> | Hub Protocol API key |
--name <name> | Pod profile to use (default: active pod) |
--list | List what can be connected and exit |
--with-mcp | Raycast only: also install the full 56-tool MCP server via mcp-remote (names overlap @synap) |
--target <name> | Legacy spelling of <thing> |
--pin-workspace <id> | Legacy spelling of --workspace |
--pin-project <id> | Legacy spelling of --project |
synap pods
Manage multiple Synap pod profiles and switch between them
synap pods [options] [command]synap pods list
List all configured pod profiles
synap pods list [options]synap pods add
Connect a new pod and save as a named profile
synap pods add [options] [name] [url]synap pods use
Switch active pod and propagate credentials to all agent surfaces
synap pods use [options] <name>| Option | Description |
|---|---|
--surface <surface> | Only switch this surface (raycast, claude-code, claude-desktop, cursor) |
--json | Output as JSON (incl. nextSteps for agents; full-switch only) |
synap pods update
Change a saved pod's URL in place (verifies health + whether the key must be recreated)
synap pods update [options] <name> [url]| Option | Description |
|---|---|
--url <url> | New pod URL (alternative to the positional arg) |
--yes | Non-interactive: skip prompts (won't recreate a rejected key) |
synap pods remove
Remove a pod profile
synap pods remove [options] <name>Aliases: rm
synap pods reconnect
Re-authenticate a saved pod (refresh API key without re-entering the URL)
synap pods reconnect [options] [name]synap status
Show Synap pod health and API status
synap status [options]| Option | Description |
|---|---|
--json | Dump raw status (incl. release/migration detail) as JSON |
synap doctor
Coherence preflight: pod host resolves, key authenticates, workspace/project exist on THIS pod, and why each configured key does or does not work — catches config drift in one call
synap doctor [options]| Option | Description |
|---|---|
--json | Output as JSON |
--fix | Fix key problems: finish a pending approval, give this computer its own key, or rewrite stale copies — then verify over MCP |
-v, --verbose | Every check with its details, ids and addresses |
synap versions
Show LOCAL vs NPM vs CONTROL-PLANE vs POD version drift for workspace-templates, api-types, and capabilities
synap versions [options]| Option | Description |
|---|---|
--json | Output structured {artifacts:[...]} JSON |
synap whoami
Show key owner vs EFFECTIVE user (+ isAgent), scopes/workspace, and flag env-vs-surface key divergence
synap whoami [options]| Option | Description |
|---|---|
--json | Output as JSON |
synap update
Show how to update the CLI
synap update [options]synap switch
Switch active pod (interactive picker if no name given)
synap switch [options] [name]synap connections
Show everything connected: which pod each agent points at, and which tools the pod has connected
synap connections [options]Aliases: conn
synap app
Connect an app in this repo to your pod (synap.app.json)
synap app [options] [command]synap app init
Write synap.app.json (asks name, pod, permissions) and register the app
synap app init [options]synap app connect
Request the app's access, await approval, then write its key into the deploy target
synap app connect [options]synap mcp
Connect any AI client to your pod's MCP server (the ambient tool layer)
synap mcp [options] [command]synap mcp url
Print a ready-to-paste MCP connection (URL + key + snippets) for UI clients like ChatGPT
synap mcp url [options]| Option | Description |
|---|---|
--client <name> | Name the dedicated agent key after the target client |
--workspace <id> | Scope to a specific workspace (omit for pod-wide) |
--project <id> | Focus the agent on a project (narrows every tool call; orthogonal to --workspace) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap mcp verify
Health-check: is the pod's /mcp endpoint reachable and the key valid?
synap mcp verify [options]| Option | Description |
|---|---|
--workspace <id> | Scope to a specific workspace |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap mcp bridge
Stdio MCP server for Claude Code: forwards to the pod and names the conversation (spawned by Claude Code, not run by hand)
synap mcp bridge [options]| Option | Description |
|---|---|
--url <url> | The pod MCP URL to forward to |
synap mcp use-bridge
Connect Claude Code through the stdio bridge, so work can be traced to and reopened in its conversation
synap mcp use-bridge [options]| Option | Description |
|---|---|
--off | Switch back to the direct http connection |
synap mcp connect
Write the MCP config for a file-configurable client (Claude Code, Cursor, Desktop, ChatGPT, …) — alias of synap agents add <client>
synap mcp connect [options] [client]| Option | Description |
|---|---|
--name <name> | Pod profile to connect |
synap mcp connect-chatgpt
Connect ChatGPT (web) to Synap — API-key connector to your pod
synap mcp connect-chatgpt [options]| Option | Description |
|---|---|
--name <name> | Pod profile to connect |
synap mcp connect-chatgpt-oauth
Connect ChatGPT (web) via Control Plane OAuth — multi-pod, no key to paste
synap mcp connect-chatgpt-oauth [options]| Option | Description |
|---|---|
--name <name> | Pod profile to connect |
synap mcp connect-claude
Print the claude.ai (web) OAuth connection steps — paste a URL, approve in the browser, done
synap mcp connect-claude [options]| Option | Description |
|---|---|
--cp-url <url> | Control-plane origin override (default: derived from the pod host) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap mcp ui-setup
Print the exact form fields to fill in the client's MCP/Connector UI (ChatGPT, Codex, Cursor, etc.)
synap mcp ui-setup [options] <client>| Option | Description |
|---|---|
--name <name> | Pod profile to use (default: active) |
--workspace <id> | Scope to a specific workspace |
--project <id> | Focus the agent on a project |
--json | Output as JSON |
synap login
Connect your Synap account (private templates) + your pods
synap login [options]| Option | Description |
|---|---|
--reconnect [name] | Re-authenticate a saved pod without re-entering its URL |
synap orient
Show a lightweight lens map: who you are, your projects (companies/initiatives), and workspaces (operational domains)
synap orient [options]| Option | Description |
|---|---|
--json | Output as JSON |
--details | Include per-workspace profiles + entity counts (heavier) |
--workspace <space> | Orient ONE space by name or id, for this call only — shows its brief (purpose, kinds, rules, skills) without changing your pinned lens |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap digest
Summarize what's in a workspace or project (counts + key entities)
synap digest [options]| Option | Description |
|---|---|
--workspace <id|name> | Workspace to digest (defaults to active workspace lens) |
--project <id|name> | Project to digest (cross-cutting lens) |
--json | Output raw JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap diagnose
See what an AI did — the run feed, or one run's nodes (by id or flow name)
synap diagnose [options] [run]| Option | Description |
|---|---|
--flow <automation|playbook|capture|capability|session|chat> | Restrict the feed, or narrow the run lookup to one flow |
--flow-id <id> | Restrict the feed to one flow's runs (automationId / playbookId) |
--limit <n> | Max runs in the feed |
--json | Output raw JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap use
Set the active workspace (by ID or name) — short form of synap workspace use. Default scope: this directory
synap use [options] <workspace>| Option | Description |
|---|---|
--session | Ephemeral: scope only this Claude Code session, don't persist |
--global | Durable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap project
Manage + focus the project lens (a commitment, spanning workspaces): list, new, use, clear
synap project [options] [command]synap project list
List projects on the active pod, with the pinned one marked (bare synap project runs this)
synap project list [options]| Option | Description |
|---|---|
--json | Output as JSON (incl. nextSteps for agents) |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap project new
Create a project (a commitment you are driving, with whom) on the active pod, then guide you to pin + add to it
synap project new [options] <name>| Option | Description |
|---|---|
--description <text> | Optional one-line description |
--json | Output as JSON (incl. nextSteps for agents) |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap project use
Pin the active project (durable, like synap use <workspace>). Ref = uuid, slug, or <pod>/<slug> — cross-pod refs switch the active pod too
synap project use [options] <ref>| Option | Description |
|---|---|
--session | Ephemeral: scope only this Claude Code session, don't persist (cross-pod refs refused) |
--global | Durable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap project clear
Clear the active project focus (durable by default)
synap project clear [options]| Option | Description |
|---|---|
--session | Ephemeral: clear only this Claude Code session's project |
--json | Output as JSON |
synap project purge
HARD teardown: delete a project + its pod-wide-exclusive entities (owner-only, irreversible)
synap project purge [options] <target>| Option | Description |
|---|---|
--confirm <name> | Confirm non-interactively by passing the exact project name |
--yes | Skip the interactive name prompt (uses the resolved name) |
--json | Output raw JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap lens
Show the effective lens (workspace + project + focus session) and WHICH rung set each one
synap lens [options]| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap ask
Ask your pod anything — returns a synthesized answer with its sources
synap ask [options] <query>| Option | Description |
|---|---|
--workspace <id> | Scope to a specific workspace (omit for pod-wide) |
--limit <n> | Max results per substrate Default: "10". |
--json | Output as JSON |
--session | Scope retrieval to the active session context |
--raw | Skip synthesis: show the raw per-substrate matches instead |
--compare | A/B diagnostic: show baseline vs Horizon rankers side-by-side (read-only, does not change the answer) |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap capture
Capture knowledge: smart capture "<free text>" (AI structures it). For canonical typed Knowledge, use create entity --profile=knowledge --props='{"knowledgeForm":"insight|caution"}'.
synap capture [options] [text]| Option | Description |
|---|---|
--type <type> | Legacy compatibility typed mode (gotcha|lesson|decision|reference); new automation should use knowledgeForm |
--claim <text> | Typed mode: one-line assertion (required with --type) |
--title <text> | Typed mode: short name, 80 characters or less (default: the claim's first sentence, never cut) |
--content <markdown> | Typed mode: full Markdown explanation, stored as the linked Knowledge note |
--why <text> | Reasoning or context |
--evidence <text> | Supporting file path, URL, or code snippet |
--tags <csv> | Comma-separated tags e.g. repo:synap-backend,layer:migrations |
--session | Link captured knowledge to the active session |
--pod-wide | GLOBAL lane: pod-wide cross-cutting runbook (→ knowledge_keys), visible in every workspace |
--global | Alias for --pod-wide |
--key <ns:slug> | Stable key for a --pod-wide runbook (derived from --type + --claim if omitted) |
--team | Pin to the first product workspace (default: omit workspaceId — server-derived / pod-wide preferred for knowledge) |
--workspace <id> | Explicit workspace pin (otherwise workspaceId is omitted for knowledge) |
--project <id|name> | Pin the capture to a project (id or name) — overrides SYNAP_PROJECT_ID / the session lens |
--yes | Skip the y/N confirmation prompt (smart mode) |
--json | Output as JSON |
synap import
Import files, folders, or URLs into the pod (AI capture pipeline, or Superwhisper store-first)
synap import [options] [inputs...]| Option | Description |
|---|---|
--workspace <id|name> | Override AI workspace routing |
--project <id|name> | Override AI project routing |
--home-map <pairs> | Multi-home path map: pathSubstring=workspaceNameOrId pairs (e.g. "Projects=Builder,Posts=Content OS"). Matched batch paths are rewritten with the workspace name as the first segment so placement heuristics pin the right home. No product defaults. |
--dry-run | Preview only — do not write |
--yes | Skip confirmation / auto-confirm store-first |
--session | Link created entities to the active session |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
--source <name> | Adapter: superwhisper (paired meta.json+output.wav store-first) |
--store-first | Skip AI structure; store units as pod-wide notes (+ optional audio) |
--keep-raw | Keep the original file and link it to the created entity (default: extract, then discard the bytes) |
--with-audio | Upload WAV provenance (default on for --source superwhisper --store-first) |
--no-with-audio | Transcript-only (no WAV upload) |
--limit <n> | Max Superwhisper units to process |
--concurrency <n> | Parallel unit uploads (1–4) |
--no-resume | Ignore local import ledger (re-import all) |
--job-status <jobId> | Re-poll a background corpus import started by an earlier run (no waiting) |
synap upload
Upload a file to the pod as an entity (>10MB goes direct to storage: video ≤500MB, audio ≤100MB, zip ≤200MB)
synap upload [options] <path>| Option | Description |
|---|---|
--workspace <id> | Pin the entity to this workspace (explicit placement) |
--profile <slug> | Entity kind to create (default: file), e.g. brand-asset |
--prop <key=value> | Entity property (repeatable) |
--attach <entityId> | After upload, link the document to this entity (references relation) |
--title <title> | Title for the created document |
--open | Open in the Synap desktop app after upload |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Examples:
synap upload ./report.pdf
synap upload ./logo.png --title "Brand logo" --workspace <id>
synap upload ./spec.pdf --attach <entityId>
synap upload ./logo.svg --profile brand-asset --prop variant=dark --workspace <id>
synap upload ./launch.mp4 --workspace <id>
synap upload ./report.pdf --opensynap subscribe
Stream pod events as NDJSON (long-poll)
synap subscribe [options]| Option | Description |
|---|---|
--event <pattern> | Filter by event type pattern (e.g. proposal.*) |
--limit <n> | Events per poll Default: "20". |
--json | NDJSON output |
--pod-url <url> | |
--api-key <key> |
synap home
Show the active workspace's home bento layout (what cells are on screen)
synap home [options]| Option | Description |
|---|---|
--workspace <id> | Workspace to read (defaults to active workspace) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap context
Session-start context: knowledge, proposals, tasks, active sessions
synap context [options]| Option | Description |
|---|---|
--repo <name> | Filter knowledge by repo tag |
--limit <n> | Entries per section Default: "5". |
--json | NDJSON output |
--workspace <id> | Override workspace |
--pod-url <url> | |
--api-key <key> |
synap discover
Runtime discovery: entity profiles with property schemas + CLI command tree
synap discover [options]| Option | Description |
|---|---|
--json | Output as JSON (default: human-readable) |
--profiles | Show only profiles (use with --json for machine-readable schema) |
--commands | Show only the command tree |
--summary | List profile kinds without property schemas |
--profile-slugs <slugs> | Comma-separated profile slugs to load in full |
--workspace <id> | Workspace to query (defaults to active workspace) |
synap workspace
Manage + focus the workspace lens (an operational domain): list, use, clear
synap workspace [options] [command]synap workspace use
Pin the active workspace by ID or name (durable, like synap use <workspace>). Default scope: this directory
synap workspace use [options] <workspace>| Option | Description |
|---|---|
--session | Ephemeral: scope only this Claude Code session, don't persist |
--global | Durable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap workspace list
List workspaces you belong to (bare synap workspace runs this)
synap workspace list [options]| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap workspace clear
Clear the active workspace focus (durable by default)
synap workspace clear [options]| Option | Description |
|---|---|
--session | Ephemeral: clear only this Claude Code session's workspace |
--json | Output as JSON |
synap workspace provision-agent
Provision an agent-owned workspace and set it as active (idempotent)
synap workspace provision-agent [options]| Option | Description |
|---|---|
--agent-user-id <uuid> | Agent user ID (defaults to caller) |
--name <name> | Workspace display name override |
--no-use | Do not set as active workspace after provisioning |
--json | Output as JSON |
synap workspace purge
HARD teardown: delete a workspace + all its entities and blobs (owner-only, irreversible)
synap workspace purge [options] <target>| Option | Description |
|---|---|
--confirm <name> | Confirm non-interactively by passing the exact workspace name |
--yes | Skip the interactive name prompt (uses the resolved name) |
--json | Output raw JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap workspace archive
Archive a workspace (hides it, pauses its workspace automations). Governed: agents propose
synap workspace archive [options] <workspace>| Option | Description |
|---|---|
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap workspace restore
Restore an archived workspace (by id). Re-enables nothing; lists automations still paused
synap workspace restore [options] <workspace>| Option | Description |
|---|---|
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap workspace rename
Rename a workspace. Governed: agents propose
synap workspace rename [options] <workspace> <newName>| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap entity
Entity operations: move
synap entity [options] [command]synap entity move
Move entities into another workspace. Governed per entity: moved / proposed / errors
synap entity move [options] <entityIds...>| Option | Description |
|---|---|
--to <workspace> | Destination workspace id or name Required. |
--reason <text> | Why they belong there — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap list
List pod resources
synap list [options] [command]synap list workspaces
List workspaces you belong to
synap list workspaces [options]| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap list profiles
List entity profile types available in a workspace
synap list profiles [options]| Option | Description |
|---|---|
--workspace <id> | Workspace (defaults to active) |
--json | Output as JSON |
synap list views
List views in a workspace (whiteboard, kanban, bento, …)
synap list views [options]| Option | Description |
|---|---|
--type <type> | Filter by view type (e.g. whiteboard, kanban, calendar) |
--workspace <id> | Workspace (defaults to active) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap list entities
List entities on the pod
synap list entities [options]| Option | Description |
|---|---|
--workspace <id> | Scope to a workspace (omit for pod-wide) |
--profile <slug> | Filter by profile slug (e.g. person, task, note) |
--role <slug> | Filter to entities carrying this role (e.g. client, partner) |
--limit <n> | Max results Default: "50". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap show
Show an entity with its properties and all linked relations
synap show [options] <id>| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap facet
Manage roles attached to an entity (client, partner, contact, …)
synap facet [options] [command]synap facet attach
Attach a role to an entity
synap facet attach [options] <entityId> <roleSlug>| Option | Description |
|---|---|
--property <kv> | Role property as key=value (repeatable) Default: []. |
--workspace <id> | Role's lens (defaults to the active workspace) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap facet list
List the roles attached to an entity
synap facet list [options] <entityId>| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap facet detach
Detach a role — pass the facet id, or --entity <id> --role <slug>
synap facet detach [options] [facetId]| Option | Description |
|---|---|
--entity <id> | Entity id (with --role, resolves the facet to detach) |
--role <slug> | Role slug (with --entity) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap proposals
Review and act on governance proposals
synap proposals [options] [command]synap proposals list
List governance proposals (default: the pending queue)
synap proposals list [options]| Option | Description |
|---|---|
--status <status> | pending (default) | approved | auto_approved (what the agent already did) | rejected | expired (never decided) | all Default: "pending". |
--workspace <id> | Scope to a specific workspace |
--session <id> | Scope to one focus session (the agent run that filed them) |
--limit <n> | Max results Default: "20". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap proposals approve
Approve a pending proposal (interactive only — requires a TTY and a typed confirmation)
synap proposals approve [options] <id>| Option | Description |
|---|---|
--reason <text> | Optional approval note |
--verb <verb> | Same-name choice: fill_empty | keep_existing | use_capture | separate |
--existing <uuid> | Existing record id — required for fill_empty, keep_existing, and use_capture |
--yes | Accepted for symmetry with other commands, but does NOT skip the typed confirmation — approval is always deliberate |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap proposals reject
Reject a pending proposal
synap proposals reject [options] <id>| Option | Description |
|---|---|
--reason <text> | Rejection reason |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap proposals await
Block until a proposal is decided. Exit 0 approved · 1 rejected/expired/withdrawn · 2 timeout
synap proposals await [options] <id>| Option | Description |
|---|---|
--timeout <duration> | Give up after this long (e.g. 30m, 2h) Default: "30m". |
--interval <duration> | Delay between checks (e.g. 10s) Default: "10s". |
--json | Output the final status as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap worker
Run Claude Code unattended here for the sessions handed to an agent
synap worker [options]| Option | Description |
|---|---|
--agent <name> | The named agent this machine works as (its key comes from ~/.synap) Required. |
--interval <dur> | How often to check for handed sessions (e.g. 30s, 2m) Default: "30s". |
--once | Check once, run what is handed, wait for it, exit |
--cwd <dir> | Where the launched Claude Code works (default ~/Documents/Code/synap) |
--max-parallel <n> | Runs at the same time Default: "1". |
--claude-bin <path> | The claude binary Default: "claude". |
--claude-config-dir <dir> | CLAUDE_CONFIG_DIR for launched runs — picks which Claude subscription they use |
--allowed-tools <list> | Comma-separated Claude tools allowed without asking (the pod MCP server is always added) |
--skip-permissions | Launch with --dangerously-skip-permissions instead of an allow-list |
--dry-run | Claim and log what would launch, without launching Claude |
synap session
Manage focus sessions (goal-bound AI work rooms)
synap session [options] [command]synap session start
Start a new focus session and return its ID
synap session start [options]| Option | Description |
|---|---|
--goal <text> | What this session is working toward Required. |
--workspace <id> | Workspace that owns the session |
--project <id> | Project that owns the session (defaults to the active project lens; the pod accepts a workspace OR a project) |
--task-id <id> | Link session to an existing task entity |
--track <id> | Born inside a track (a project's lasting goal) — implies its project |
--template <id> | Start from a playbook (seeds currentStage from its stages) |
--no-template | Opt out of auto-matching a playbook — start ad-hoc |
--parent <id> | Push from another session — records session --spawned_from--> session (the parent stays open) |
--suspended-intent <text> | With --parent: this session BLOCKS the parent. One line naming what the parent was about to do; the parent waits until this session closes |
--criteria <file.json> | Path to a JSON file of binary acceptance criteria (SessionCriterion[]) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session list
List focus sessions in the active workspace
synap session list [options]| Option | Description |
|---|---|
--workspace <id> | Scope to a specific workspace |
--project <id> | Scope to a project (its sessions across spaces) |
--status <status> | Filter by status: active | paused | closed |
--kind <kind> | Filter by population: work | run | receipt | all Default: "all". |
--limit <n> | Max results Default: "20". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session get
Show details for a specific focus session (works for project-scoped sessions)
synap session get [options] <id>| Option | Description |
|---|---|
--workspace <id> | Workspace hint if the pod still requires it for GET |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session update
Update a focus session's progress, status, stage or goal
synap session update [options] <id>| Option | Description |
|---|---|
--workspace <id> | Workspace that owns the session (optional; inferred from the active lens) |
--progress <0-100> | Progress percentage — a whole number 0-100, not prose |
--status <status> | New status: active | paused |
--stage <key> | Advance the session's current stage (playbook stage key) |
--goal <text> | Revised goal |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session close
End a focus session (proposal pack) and optionally attach a recap
synap session close [options] <id>| Option | Description |
|---|---|
--workspace <id> | Workspace hint (optional; not required for complete) |
--recap <text> | Short summary of what was accomplished (maps to summary) |
--as <status> | How it ended: closed (default, finished) | cancelled (abandoned) | failed (could not complete) |
--json | Output full pack (or close result) as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session attach
Attach a session to this terminal — all hub calls tag X-Session-Id until detached
synap session attach [options] <id>| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session detach
Remove the active session from this terminal
synap session detach [options]| Option | Description |
|---|---|
--json | Output as JSON |
synap session current
Show the active session for this terminal (SYNAP_SESSION_ID, Claude-session lens, or .synap/lens.json)
synap session current [options]| Option | Description |
|---|---|
--json | Output as JSON |
synap session evidence
Post your own pass/fail report for one evidence-checked acceptance criterion
synap session evidence [options] <key>| Option | Description |
|---|---|
--session <id> | Focus session ID (defaults to this terminal's active session) |
--passed | The criterion is satisfied |
--failed | The criterion is not satisfied |
--detail <text> | Optional note explaining the verdict |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session evaluate
Run every pending acceptance-criterion check (evidence, capability, judge) and print the verdicts
synap session evaluate [options]| Option | Description |
|---|---|
--session <id> | Focus session ID (defaults to this terminal's active session) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap session wait
Block until the human replies in the session room, then print the reply. Exit 0 replied · 1 timeout · 2 failure (auth/network/broken read)
synap session wait [options] <sessionId>| Option | Description |
|---|---|
--since <iso> | Only answers strictly after this ISO timestamp (default: now — skips anything that predates this wait) |
--timeout <duration> | Give up after this long (e.g. 30m, 2h) Default: "30m". |
--interval <duration> | Delay between checks (e.g. 10s) Default: "10s". |
--limit <n> | Max answers per page, 1-100 Default: "20". |
--json | Output the reply(ies) — or the timeout — as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap playbook
Run playbooks — governed, reusable processes
synap playbook [options] [command]synap playbook run
Run a playbook by name or id, optionally on a subject entity
synap playbook run [options] <name-or-id>| Option | Description |
|---|---|
--subject <entityId> | The entity the playbook runs on |
--param <key=value> | Answer a declared param (repeatable; typed by the playbook) Default: []. |
--workspace <id> | Write home for the run (defaults to the playbook's own workspace) |
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track
Manage tracks — the lasting goals a project pursues
synap track [options] [command]synap track list
List a project's tracks (defaults to the active project lens)
synap track list [options]| Option | Description |
|---|---|
--project <id> | Project id (defaults to the active project lens) |
--all | Include archived tracks |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track show
Show one track: its steps and where it stands
synap track show [options] <id>| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track start
Start a track — a lasting goal — on a project
synap track start [options]| Option | Description |
|---|---|
--name <name> | The track's name (required without --playbook) |
--direction <text> | Where it is heading, one line |
--playbook <id> | Legacy: a track template (project-scoped playbook with steps) |
--project <id> | Project id (defaults to the active project lens) |
--param <key=value> | Answer a declared param (repeatable) Default: []. |
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track advance
Legacy (tracks with steps): move a track to a step; prints the session that step offers
synap track advance [options] <id> <stage>| Option | Description |
|---|---|
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track status
Pause, resume or archive a track (active|paused|archived)
synap track status [options] <id> <status>| Option | Description |
|---|---|
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track params
Answer the method's params as key=value (merged; key=null clears one)
synap track params [options] <id> <pairs...>| Option | Description |
|---|---|
--reason <text> | Why — shown to the reviewer |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap track start-step
Legacy (tracks with steps): start one step's session — on a track with no steps, use 'session start --track'
synap track start-step [options] <id>| Option | Description |
|---|---|
--stage <key> | Step key (defaults to the current step) |
--title <text> | Session name (defaults to the step's name) |
--goal <text> | Outcome (defaults to the step's goal) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill
Execute a skill in an autonomous workspace session
synap skill [options] [command]synap skill gather-context
Gather pod KG + local context (CLAUDE.md, .claude/kg-verify) for a session
synap skill gather-context [options]| Option | Description |
|---|---|
--session <id> | Focus session ID (required) |
--workspace <id> | Workspace ID (defaults to active workspace) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill suggest
Search the skill knowledge base by topic or keyword
synap skill suggest [options] <topic>| Option | Description |
|---|---|
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill get
Fetch a skill from the knowledge base by slug and print its body
synap skill get [options] <slug>| Option | Description |
|---|---|
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill add
Add skill(s) to your pod from: bundled · a local path · ~/.claude/skills/ · owner/repo · a git URL
synap skill add [options] <source>| Option | Description |
|---|---|
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill list
List the instruction skills installed on your pod
synap skill list [options]Aliases: ls
| Option | Description |
|---|---|
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
--debug | Show resolved credentials |
synap skill approve
Approve a skill so it loads (agent-authored skills are born unapproved)
synap skill approve [options] <slug-or-id>| Option | Description |
|---|---|
--revoke | Revoke approval instead of granting it |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill remove
Remove a skill from your pod by slug
synap skill remove [options] <slug>Aliases: rm
| Option | Description |
|---|---|
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill sync
Bulk-import local skills from ~/.claude/skills/ into the pod
synap skill sync [options]| Option | Description |
|---|---|
--from <path> | Skills directory path (default: ~/.claude/skills) |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap skill verify-code
Run the project's type-check/test gate and store the result on the session
synap skill verify-code [options]| Option | Description |
|---|---|
--session <id> | Focus session ID Required. |
--workspace <id> | Workspace that owns the session Required. |
--cmd <command> | Gate command to run (e.g. 'pnpm type-check') Required. |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap browse
Browse entities in the active workspace, optionally filtered by profile type or role
synap browse [options] [profile]| Option | Description |
|---|---|
--workspace <id> | Scope to a specific workspace |
--role <slug> | Filter to entities carrying this role (e.g. client, partner) |
--limit <n> | Max results Default: "20". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap observe
Write and recall pod-wide user observations (AI-maintained user model)
synap observe [options] [command]synap observe write
Record an observation about the user (pod-scoped, AI-maintained)
synap observe write [options] <text>| Option | Description |
|---|---|
--category <cat> | working_style | communication | focus | technical | preference Default: "preference". |
--confidence <n> | Confidence score 0-1 Default: "0.5". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap observe recall
Search recorded user observations
synap observe recall [options] <query>| Option | Description |
|---|---|
--category <cat> | Filter by category |
--limit <n> | Max results Default: "10". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap get
Get a single pod resource
synap get [options] [command]synap get entity
Get an entity by ID
synap get entity [options] <id>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap create
Create pod resources
synap create [options] [command]synap create entity
Create a new entity
synap create entity [options]| Option | Description |
|---|---|
--profile <slug> | Profile slug (e.g. person, note, task) Required. |
--name <name> | Entity name Required. |
--content <markdown> | Long-form Markdown body, stored as the entity's linked document |
--workspace <id> | Create in this workspace |
--props <json> | Properties as JSON string Default: "{}". |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap create relation
Create a typed relation between two entities
synap create relation [options]| Option | Description |
|---|---|
--source <id> | Source entity ID Required. |
--target <id> | Target entity ID Required. |
--type <type> | Relation type (e.g. extends, part_of, implements, governs, related_to) Required. |
--workspace <id> | Workspace context |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap set
Update pod resources
synap set [options] [command]synap set entity
Update entity properties
synap set entity [options] <id>| Option | Description |
|---|---|
--props <json> | Properties as JSON string Required. |
--workspace <id> | Workspace ID (sent in PATCH body so workspace-scoped automations fire) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap agents
Manage agent principals on your pod (one per type for you; local keys are a cache)
synap agents [options] [command]synap agents list
List your agents on this pod (one per type). Use --local for ~/.synap cache only.
synap agents list [options]| Option | Description |
|---|---|
--json | Output as JSON |
--local | List only the local ~/.synap agent cache |
synap agents add
Bring an agent into the pod: a client (claude-code, cursor, codex, …), your own (--name → URL + key), or pick from this machine (no kind)
synap agents add [options] [kind]| Option | Description |
|---|---|
--name <name> | Name your own agent (e.g. researcher) — prints a URL + key to paste |
--template <tmpl> | Your own agent's template: twin | assistant | custom (default: custom) |
--type <type> | Explicit agent type for your own agent (default: a slug of --name) |
--role <role> | Workspace role: admin | editor | viewer (default: editor) |
--workspace <id> | Focus on one workspace (default: pod-wide) |
--project <id> | Focus on one project (composable with --workspace) |
--with-mcp | Raycast only: also install the full MCP server via mcp-remote |
--api-key <key> | Register a key you already hold, on this machine only (mints nothing) |
--label <label> | Human-readable description |
synap agents create
Deprecated — use synap agents add (same flags)
synap agents create [options]| Option | Description |
|---|---|
--template <tmpl> | Agent template: twin | assistant | custom (default: custom) |
--name <name> | Agent name (not needed for twin — auto-generated) |
--type <type> | Agent type string for custom agents (default: matches template) |
--role <role> | Workspace role: admin | editor | viewer (default: editor) |
--workspace <id> | Focus on one workspace (default: pod-wide) |
--project <id> | Focus on one project |
synap agents rotate-key
Rotate the Hub Protocol API key for an agent (local cache only)
synap agents rotate-key [options] <name-or-id>synap agents remove
Remove a named agent identity (local cache only)
synap agents remove [options] <name>Aliases: rm
synap agents info
Show details for a named agent identity (local cache only)
synap agents info [options] <name>| Option | Description |
|---|---|
--show-key | Print the MCP URL and the full API key |
--snippets | Print paste-ready configs (Claude Code, Cursor, stdio clients) |
synap agent
Run autonomous agent loops against the IS, or schedule recurring goals
synap agent [options] [command]synap agent ask
Send one message to the workspace's deployed agent and print its reply (multi-turn: reuses one thread)
synap agent ask [options] <message>| Option | Description |
|---|---|
--workspace <id|name> | Workspace to talk to (uses active workspace/lens if omitted) |
--thread <id> | Target an existing thread/channel id instead of the default CLI chat thread |
--new | Start a fresh thread instead of continuing the persistent CLI chat thread |
--agent-type <type> | Requested agent type hint (backend currently routes to the orchestrator) |
--timeout <seconds> | How long to wait for the agent's reply (default: 90) |
--json | Machine-readable output { ok, reply, threadId, workspaceId } |
--pod-url <url> | Override pod URL |
--api-key <key> | Override API key |
synap agent chat
Interactive REPL conversation with the workspace's deployed agent
synap agent chat [options]| Option | Description |
|---|---|
--workspace <id|name> | Workspace to talk to (uses active workspace/lens if omitted) |
--thread <id> | Target an existing thread/channel id instead of the default CLI chat thread |
--new | Start a fresh thread instead of continuing the persistent CLI chat thread |
--agent-type <type> | Requested agent type hint (backend currently routes to the orchestrator) |
--timeout <seconds> | How long to wait for each reply (default: 90) |
--pod-url <url> | Override pod URL |
--api-key <key> | Override API key |
synap agent run
Run an autonomous agent toward a goal using the Intelligence Service
synap agent run [options]| Option | Description |
|---|---|
--goal <text> | What the agent should accomplish Required. |
--persona <type> | researcher | assistant | developer (default: researcher) |
--model <model> | IS model alias, e.g. synap/advanced (default: synap/advanced) |
--workspace <id> | Workspace to store results in (uses active workspace if omitted) |
--max-steps <n> | Max reasoning steps before auto-saving (default: 12) |
--dry-run | Print config without running |
--pod-url <url> | Override pod URL |
--api-key <key> | Override API key |
synap agent schedule
Add, list, or remove recurring agent schedules
synap agent schedule [options]| Option | Description |
|---|---|
--goal <text> | Goal for the scheduled agent |
--name <label> | Name for this schedule (required when adding) |
--every <interval> | hourly | daily | weekly |
--persona <type> | researcher | assistant | developer (default: researcher) |
--model <model> | IS model alias (default: synap/advanced) |
--workspace <id> | Workspace to store results in |
--run-now | Also run immediately after creating the schedule |
--list | List all configured schedules |
--remove <name> | Remove a schedule by name |
--pod-url <url> | Override pod URL |
--api-key <key> | Override API key |
synap agent tick
Check due schedules and run them — wire this to crontab: 0 * * * * synap agent tick
synap agent tick [options]| Option | Description |
|---|---|
--dry-run | Show what would run without executing |
--pod-url <url> | Override pod URL |
--api-key <key> | Override API key |
synap automate
Ask the workspace agent to prepare a governed automation proposal
synap automate [options] <instruction>| Option | Description |
|---|---|
--workspace <id|name> | Workspace to use (uses active workspace/lens if omitted) |
--thread <id> | Continue an existing agent thread/channel |
--new | Start a fresh agent thread |
--timeout <seconds> | How long to wait for the agent's reply (default: 90) |
--json | Machine-readable output { ok, reply, threadId, workspaceId } |
--pod-url <url> | Override pod URL |
--api-key <key> | Override API key |
synap rule
State a standing rule in plain language — classified, shown, then governed-created
synap rule [options] [command] [text]| Option | Description |
|---|---|
--workspace <id> | Workspace to scope the rule to (uses active workspace if omitted) |
--pod-wide | Scope the rule to the whole pod, ignoring the active workspace |
--yes | Skip the one-off confirmation (never skips a clarification) |
--json | Output raw JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap rule list
List rules with their intent, scope, and whether a behaviour is attached
synap rule list [options]| Option | Description |
|---|---|
--workspace <id> | Filter by workspace |
--json | Output raw JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap automation
Create, manage, and inspect pod automations
synap automation [options] [command]synap automation list
List automations on the pod
synap automation list [options]| Option | Description |
|---|---|
--workspace <id> | Filter by workspace |
--status <status> | Filter by status (active|draft|paused|error) |
--json | Output raw JSON |
synap automation describe
Show full details of an automation
synap automation describe [options] <id>| Option | Description |
|---|---|
--workspace <id> | |
--json |
synap automation create
Create an automation (quick flags or --from file.yaml)
synap automation create [options]| Option | Description |
|---|---|
--name <name> | Automation name (required in quick mode) |
--trigger <spec> | event:<pattern> | cron:<expr> | webhook | manual |
--filter <kv> | key=value filter (event triggers, repeatable) Default: []. |
--action <type> | notify | channel-message | none (default: none) |
--message <text> | Message content for notify/channel-message |
--channel <id> | Channel ID for channel-message action |
--status <status> | draft (default) | active |
--description <text> | Description |
--workspace <id> | Workspace ID |
--from <file> | Create from YAML/JSON file instead of flags |
synap automation enable
Activate an automation
synap automation enable [options] <id>| Option | Description |
|---|---|
--workspace <id> |
synap automation disable
Pause an automation
synap automation disable [options] <id>| Option | Description |
|---|---|
--workspace <id> |
synap automation delete
Delete an automation
synap automation delete [options] <id>| Option | Description |
|---|---|
--workspace <id> | |
--force | Skip confirmation prompt |
synap automation schema
Fetch the automation DSL schema from the pod (AI context)
synap automation schema [options]| Option | Description |
|---|---|
--write-context [path] | Write markdown context file for Claude Code |
--json | Output raw JSON instead of formatted markdown |
synap graph
Low-level BFS graph traversal from an entity (prefer synap ask — graph is one of its signals)
synap graph [options]| Option | Description |
|---|---|
--entity <id> | Start entity ID Required. |
--depth <n> | Traversal depth (max 3) Default: "2". |
--json | Raw JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap centrality
Inspect PageRank centrality (entity_centrality) and trigger a recompute
synap centrality [options] [command]synap centrality status
Show whether PageRank centrality has populated + the top central entities
synap centrality status [options]| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap centrality recompute
Enqueue a PageRank centrality recompute (runs in the background)
synap centrality recompute [options]| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap events
Show event chain for an entity or recent pod events
synap events [options]| Option | Description |
|---|---|
--entity <id> | Filter by entity ID (subjectId) |
--limit <n> | Number of events Default: "20". |
--json | Raw JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap view
Manage views
synap view [options] [command]synap view create
Create a view (table, kanban, bento, …)
synap view create [options]| Option | Description |
|---|---|
--type <type> | View type: table|kanban|bento|list|grid|gallery|calendar|masonry|flow|matrix|branch_tree|whiteboard Required. |
--profile <slug> | Entity profile to display (passed as profileId) |
--name <name> | View name |
--workspace <id> | Workspace ID |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap view list
List views in the active workspace
synap view list [options]| Option | Description |
|---|---|
--type <type> | Filter by view type (e.g. whiteboard, kanban, calendar) |
--workspace <id> | Workspace ID |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap view arrange
Replace the widget arrangement of a bento view
synap view arrange [options] <viewId>| Option | Description |
|---|---|
--file <path> | JSON file containing widget layout (array or { widgets: [...] }) |
--workspace <id> | Workspace ID |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Examples:
synap view arrange <viewId> --file layout.json
echo '[{"id":"w1","kind":"widget","x":0,"y":0,"w":6,"h":4}]' | synap view arrange <viewId>
Layout format (array of BentoWidget):
[{ "id": "<widgetId>", "kind": "widget|view|entity", "x": 0, "y": 0, "w": 6, "h": 4, "config": {} }]synap explain
Full capability map — what Synap can do and how (no network required)
synap explain [options] [topic]synap open
Open in the Synap desktop app. Use: open <kind> <id> or open <id> (auto-resolves type)
synap open [options] <kind-or-id> [id]synap doc
Create and update markdown documents on the pod
synap doc [options] [command]synap doc create
Create a new markdown document
synap doc create [options]| Option | Description |
|---|---|
--title <title> | Document title Required. |
--content <text> | Markdown content (inline) |
--file <path> | Read content from a file |
--workspace <id> | Workspace to create the document in |
--open | Open in the Synap desktop app after creation |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Examples:
synap doc create --title "My Notes" --content "# Hello"
synap doc create --title "My Notes" --file ./notes.md --open
echo "# Draft" | synap doc create --title "Draft"synap doc update
Update a document's content: the whole body, or one section (--section). Governed: an agent's edit is proposed.
synap doc update [options] <documentId>| Option | Description |
|---|---|
--content <text> | New markdown content (inline) |
--file <path> | Read new content from a file |
--section <id> | Write ONE section by id (content = the section body) instead of the whole document |
--section-title <title> | The section heading (required with --section) |
--base-revision <n> | The revision you read; refused if the document changed since |
--open | Open in the Synap desktop app after update |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Examples:
synap doc update <id> --content "# Updated"
synap doc update <id> --file ./notes.md
cat notes.md | synap doc update <id>
synap doc update <id> --section risks --section-title "Risks" --file ./risks.mdsynap doc reference
Create an external reference document (points at a URL — no bytes stored)
synap doc reference [options] <url>| Option | Description |
|---|---|
--title <title> | Document title Required. |
--workspace <id> | Workspace to create the reference in |
--open | Open in the Synap desktop app after creation |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Examples:
synap doc reference https://example.com/spec --title "Vendor spec"synap cell
Define and bundle frame cells for the Synap runtime
synap cell [options] [command]synap cell define
Create or update a frame cell on the pod from ESM source
synap cell define [options]| Option | Description |
|---|---|
--name <name> | Cell display name Required. |
--file <path> | ESM source file (or pipe stdin) |
--type-key <key> | Explicit typeKey (default: generated:<slug>) |
--deps <json> | Dependency map JSON, e.g. '{"recharts":"2.12.0"}' |
--view-types <list> | Comma-separated view types this cell can render as a VIEW RENDERER, e.g. "list,table,kanban". Omit to leave an existing affinity untouched; pass "" to clear it |
--content-kind <kind> | What this cell renders — entity-detail | entity-card | entity-profile | collection | widget (default: widget, which is placeable but never offered as a profile renderer) |
--workspace <id> | Workspace to scope the cell to (default: your active workspace lens — run synap lens to see it) |
--description <text> | Short description |
--open | Open in the Synap desktop app after define |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Without --view-types / --content-kind a cell installs cleanly but can never be
PICKED as a view or profile renderer — it is only placeable on a bento.
Examples:
synap cell define --name "Revenue Chart" --file ./chart.js
synap cell define --name "Revenue Chart" --file ./chart.js --deps '{"recharts":"2.12.0"}'
synap cell define --name "Deal Board" --file ./board.js --view-types kanban,table --content-kind collection
synap cell define --name "Contact Page" --file ./contact.js --content-kind entity-detail
cat chart.js | synap cell define --name "Revenue Chart"synap cell build
Bundle a multi-file cell/app into a single ESM module the runtime expects
synap cell build [options] <entry>| Option | Description |
|---|---|
--out <file> | Output file path (default: <entry>.bundle.js) |
--bundle-deps | Inline all third-party deps into the bundle (only react/react-dom stay external) — output has deps={} and the runtime CSP drops esm.sh entirely |
--self-contained | Build ONE complete HTML document (React, CSS, brand fonts inlined; nothing external) — the code of a rendererType "mcp-app" cell |
--fonts | With --self-contained: require the inlined brand fonts (default: include when @synap-core/design-tokens resolves) |
--no-fonts | With --self-contained: skip the inlined brand fonts |
--define | Chain into cell define after bundling (requires --name) |
--name <name> | Cell name (required with --define) |
--type-key <key> | Explicit typeKey (used with --define) |
--deps <json> | Override dependency versions as JSON, e.g. '{"react":"18.3.0"}' |
--view-types <list> | Comma-separated view-renderer affinity (used with --define), e.g. "list,table" |
--content-kind <kind> | entity-detail | entity-card | entity-profile | collection | widget (used with --define) |
--workspace <id> | Workspace (used with --define) |
--description <text> | Description (used with --define) |
--open | Open in browser after define (used with --define) |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
Output: a single ESM file.
Default mode: bare imports (react, recharts, …) are externalized and emitted
as a deps map. At runtime Synap resolves them via esm.sh importmap.
--bundle-deps mode: only react/react-dom are externalized (React is
host-inlined at runtime, never via esm.sh); everything else is bundled into
the output, so the deps map is empty. A cell built this way reaches no esm.sh
origin at runtime — the runtime CSP collapses to drop it entirely.
Examples:
synap cell build ./src/chart.tsx --out ./dist/chart.js
synap cell build ./src/chart.tsx --out ./dist/chart.js --define --name "Revenue Chart"
synap cell build ./src/chart.tsx --out ./dist/chart.js --bundle-depssynap artifact
Create and manage HTML artifacts as Synap documents
synap artifact [options] [command]synap artifact create
Create an HTML artifact from a local file
synap artifact create [options]| Option | Description |
|---|---|
--html <file> | HTML file to upload Required. |
--name <name> | Document title (default: filename) |
--workspace <id> | Workspace context |
--open | Open in the Synap desktop app after creation |
--json | JSON output |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap connect-service
Connect an external service (Google, GitHub, Notion, Linear, Slack, …)
synap connect-service [options] [service]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap tools
Add and manage external service tools and their credentials
synap tools [options] [command]synap tools list
List available tools and their connection status
synap tools list [options]| Option | Description |
|---|---|
--json | Output as JSON |
--workspace <id> | Workspace context |
synap tools connect
Connect a credential to a tool (OAuth via the connection broker, or vault)
synap tools connect [options] <service>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap tools sync
Trigger a manual sync for a connected tool
synap tools sync [options] <provider>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap tools disconnect
Revoke a tool's connection
synap tools disconnect [options] <provider>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--force | Skip confirmation |
synap tools schema
Fetch tool schema and supported providers (AI context)
synap tools schema [options]| Option | Description |
|---|---|
--write-context [path] | Write to .claude/TOOLS_CONTEXT.md |
--json | Output raw JSON instead of formatted markdown |
synap pod
Show the whole configured pod — workspaces (with provenance), capabilities/automations/playbooks, and feed links
synap pod [options] [command]| Option | Description |
|---|---|
--json | Output the full structured graph as JSON |
--orphans | Only show orphan/ad-hoc workspaces and their template-match suggestions |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap pod adopt
Link an orphan/ad-hoc workspace (by name or id) to a matching template — makes it version-tracked
synap pod adopt [options] <workspaceNameOrId>| Option | Description |
|---|---|
--template <slug> | The template slug to adopt this workspace into Required. |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap vendor
Your marketplace publisher profile (what packages are attributed to)
synap vendor [options] [command]synap vendor create
Create your publisher profile — do this BEFORE your first publish
synap vendor create [options] <slug>| Option | Description |
|---|---|
--name <name> | Display name (defaults to a title-cased slug) |
--description <text> | Short description of you or your studio |
--website <url> | Website URL (must be a full URL) |
--json | Output as JSON |
synap vendor show
Show whether you have a publisher profile
synap vendor show [options]| Option | Description |
|---|---|
--json | Output as JSON |
synap market
Browse + install packages (workspaces, capabilities, skills, workflows, views, cells) into a project
synap market [options] [command]| Option | Description |
|---|---|
--list | List and exit (the default action) |
--search <query> | Filter by name/description/slug |
--type <type> | Filter by package type (workspace|capability|skill|workflow|view|cell) |
--json | Output as JSON |
synap market install
Install a package by slug into a project — workspaces install now; other types route you to the right surface
synap market install [options] <slug>| Option | Description |
|---|---|
--project <id> | Optionally tag the seeded entities to a project (installs are pod-wide by default) |
--workspace <id> | Acting workspace (UUID) a workflow/automation package is added to (required for that kind; defaults to your active lens). Ignored for pod-wide kinds |
--onto <workspaceId> | Reconcile this template ONTO an existing workspace (additive) instead of creating a new one |
--dry-run | Preview the create path write-free — report would-create / reuse / conflicts, install nothing |
--timeout <seconds> | How long to wait for the apply to finish (default: 120) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap market update
Check installed packages for drift against the catalog, and re-apply the ones that are stale (all with --yes, specific ones with explicit slugs)
synap market update [options] [slugs...]| Option | Description |
|---|---|
--yes | Apply every available update without prompting (no slugs required), agreeing to every data change it lists |
--accept-data-changes <opKeys> | Agree to exactly these data changes (comma-separated opKeys from the preview) |
--dry-run | Force the preview path — never apply, even with --yes |
--timeout <seconds> | How long to wait for each package's apply to finish (default: 120) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap market installed
List packages installed on this pod — a pure read, no writes (pairs with 'market update' to check drift)
synap market installed [options]| Option | Description |
|---|---|
--outdated | Only show packages with an update available |
--tree | Show the composition graph — package → templates → resulting workspaces, marking shared nodes |
--layers | Show the composition graph as a flat DAG — one row per slug, bedrock-first, with true fan-in counts |
--json | Output as JSON |
synap market workspaces
List your workspaces with their template-attachment status — find the one that isn't attached yet (pure read)
synap market workspaces [options]| Option | Description |
|---|---|
--unattached | Only show workspaces that need attention (unattached or missing a version stamp) |
--json | Output as JSON |
synap market attach
Reconcile a marketplace template onto an existing workspace + version-stamp it — how you relink a workspace installed before the marketplace
synap market attach [options] <workspaceId>| Option | Description |
|---|---|
--slug <slug> | Template to attach (inferred from the workspace's existing attachment or domain when omitted) |
--project <id> | Optionally tag the reconciled entities to a project |
--timeout <seconds> | How long to wait for the apply to finish (default: 120) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap market scaffold
Write a minimal valid <slug>.template.yaml to edit in place (refuses to overwrite)
synap market scaffold [options] <slug>| Option | Description |
|---|---|
--kind <kind> | Scaffold a standalone package instead of a workspace template: cell, view, workflow, capability, skill |
--json | Output as JSON |
synap market validate
Validate a local template file against the shared template validator — fast author feedback
synap market validate [options] <file>| Option | Description |
|---|---|
--json | Output the validator result as JSON |
synap market publish
Validate then publish a template (or a standalone cell/view package) to the marketplace (private by default) — pass a file, --from-workspace <id>, or --from-project <id>. Non-official publish never uses the synap-official vendor. Founder: --official [slug...] publishes the official catalog from the monorepo checkout (alias of synap catalog publish --official --kind workspace)
synap market publish [options] [targets...]| Option | Description |
|---|---|
--official | Publish the OFFICIAL Synap catalog (all templates, or the named slugs) from the monorepo checkout — requires a synap login session that owns the synap-official vendor; previews and asks first |
--templates-dir <dir> | With --official: path to the catalog package — synap-app/packages/catalog or workspace-templates (default: found by walking up from cwd) |
--dry-run | With --official: preview what would change against the live catalog, publish nothing |
--yes | With --official: skip the confirmation prompt |
--public | Publish as PUBLIC (default is private) |
--private | Publish as private (the default — stated explicitly) |
--from-workspace <id> | Serialize a live workspace into a template and publish it (instead of a file) |
--from-project <id> | Serialize a live project's used workspaces into a suite package (tags: suite, require deps) and publish it |
--price <usd> | Stamp pricingModel=one_time + priceUsd (dollars→cents). Settlement/Stripe is not this wave — columns only. |
--json | Output as JSON |
--pod-url <url> | Pod URL override (for --from-workspace / --from-project) |
--api-key <key> | API key override (for --from-workspace / --from-project) |
--no-bundle-deps | Publish a cell's codeFile with external deps via esm.sh instead of bundling them in (default: bundled) |
synap market unpublish
Flip a published package back to private (owner only)
synap market unpublish [options] <slug>| Option | Description |
|---|---|
--json | Output as JSON |
synap templates
See every workspace's template status (attached, drifted, or unattached) and connect them — the one home for template health
synap templates [options] [command]| Option | Description |
|---|---|
--needs-attention | Show only workspaces that need action (drifted / unstamped / unattached-with-suggestion) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap templates attach
Connect a workspace (by NAME or id) to a template — suggests the right one so you don't guess a slug
synap templates attach [options] <workspace>| Option | Description |
|---|---|
--slug <slug> | Force a specific template instead of the suggestion |
--yes | Accept a confident (domain-match) suggestion without prompting — for scripts |
--project <id> | Optionally tag the reconciled entities to a project |
--timeout <seconds> | How long to wait for the apply to finish (default: 120) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap templates update
Apply template updates — 'update all' (or --yes) for every drifted workspace, or name specific slugs. Bare 'update' previews what's available.
synap templates update [options] [slugs...]Aliases: updates
| Option | Description |
|---|---|
--yes | Apply every available update without prompting, agreeing to every data change it lists |
--accept-data-changes <opKeys> | Agree to exactly these data changes (comma-separated opKeys from the preview) |
--dry-run | Preview only — never apply |
--timeout <seconds> | How long to wait for each apply (default: 120) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap templates retire
Move a retired template's space into its replacement (by template slug, workspace name or id). Shows the plan, asks, then moves through the pod — never deletes.
synap templates retire [options] <target>| Option | Description |
|---|---|
--dry-run | Show the plan only — move nothing |
--yes | Move without asking (for scripts) |
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap catalog
Validate, diff and publish the OFFICIAL template catalog (workspaces, capabilities, skills, packs, automations) from the monorepo checkout
synap catalog [options] [command]synap catalog validate
Validate the catalog (per-kind schema, cross-kind refs, goal grammar, duplicates) — offline
synap catalog validate [options] [slugs...]| Option | Description |
|---|---|
--kind <kind> | Only this kind: workspace | capability | skill | pack | automation |
--catalog-dir <dir> | Path to the catalog package (default: found by walking up from cwd) |
--json | Output as JSON |
synap catalog diff
Show what would change against the live control-plane catalog (new / changed / unchanged)
synap catalog diff [options] [slugs...]| Option | Description |
|---|---|
--kind <kind> | Only this kind: workspace | capability | skill | pack | automation |
--catalog-dir <dir> | Path to the catalog package (default: found by walking up from cwd) |
--json | Output as JSON |
synap catalog publish
Validate, preview the diff, confirm, then publish to the control plane — founder only: --official + a synap login session that owns synap-official
synap catalog publish [options] [slugs...]| Option | Description |
|---|---|
--kind <kind> | Only this kind: workspace | capability | skill | pack | automation |
--catalog-dir <dir> | Path to the catalog package (default: found by walking up from cwd) |
--json | Output as JSON |
--official | Publish as the synap-official vendor (required) |
--dry-run | Preview the diff only — publish nothing |
--yes | Skip the confirmation prompt |
synap capability
The one capability-first root: list, add, enable, connect, show, run a capability pack
synap capability [options] [command]Aliases: cap
synap capability list
List capabilities — one row per pack, with status, connection, and verbs
synap capability list [options]| Option | Description |
|---|---|
--json | Output as JSON |
--workspace <id> | Workspace context |
synap capability add
Install a capability from the catalog — omit the name to pick from a list
synap capability add [options] [name]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap capability create
Create a capability from a JSON definition (file path, or pipe JSON via stdin)
synap capability create [options] [file]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap capability rm
Remove capability container(s) by id or name — member tools/skills untouched
synap capability rm [options] <ids...>Aliases: remove
| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--force | Skip the confirmation prompt |
synap capability enable
Turn on a capability — omit the name to pick from a list; ensures its connection, then pick which verbs it can do
synap capability enable [options] [name]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap capability connect
Connect a service — omit the name to pick from connectable services
synap capability connect [options] [name]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--reconnect | Force a fresh sign-in even if a connection already exists — fixes an expired or revoked token |
synap capability disconnect
Disconnect a capability's service — accepts a capability name or a provider id
synap capability disconnect [options] <name>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--force | Skip confirmation |
synap capability show
Show one capability's full detail: status, connection, verbs, next action
synap capability show [options] <name>| Option | Description |
|---|---|
--json | Output as JSON |
--workspace <id> | Workspace context |
synap capability run
Launch a verb — pass inputs as --key value flags
synap capability run [options] <verb> [params...]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--connection <id> | Run against a specific stored connection id |
--for <objId> | Run against the connection bound to this context object id |
synap capability test
Dry-run a verb (preview side effects without executing)
synap capability test [options] <verb>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap capability connections
Manage a capability's connections: list, add, update, rm
synap capability connections [options] [command]Aliases: conn
synap capability connections list
List a capability's connections (label, kind, default, context, id)
synap capability connections list [options] <capability>| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap capability connections add
Add a connection — prompts for label + masked value unless provided as flags
synap capability connections add [options] <capability>| Option | Description |
|---|---|
--label <label> | Connection label |
--value <value> | Secret / credential value (else prompted, masked) |
--context-type <type> | Context type this connection binds to |
--context-id <id> | Context object id this connection binds to |
--account-hint <hint> | Human-readable account hint (e.g. an email) |
--default | Mark this connection as the capability's default |
--workspace <id> | Workspace context |
synap capability connections update
Update a connection's fields; --rotate (or --value) rotates its secret
synap capability connections update [options] <capability> <connectionId>| Option | Description |
|---|---|
--label <label> | New connection label |
--value <value> | New secret / credential value |
--rotate | Prompt (masked) for a new secret value |
--context-type <type> | New context type |
--context-id <id> | New context object id |
--account-hint <hint> | New account hint |
--default | Mark this connection as the capability's default |
--workspace <id> | Workspace context |
synap capability connections rm
Remove a connection by id (confirms first)
synap capability connections rm [options] <capability> <connectionId>Aliases: remove
| Option | Description |
|---|---|
--workspace <id> | Workspace context |
synap capability sync-status
Show sync status per provider × kind × connection (phase, counts, errors) — omit provider to see all
synap capability sync-status [options] [provider]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--json | Output as JSON |
synap sync
Sync status for connected providers — see cap sync-status
synap sync [options] [command]synap sync status
Show sync status per provider × kind × connection (phase, counts, errors) — omit provider to see all. Alias of synap cap sync-status.
synap sync status [options] [provider]| Option | Description |
|---|---|
--workspace <id> | Workspace context |
--json | Output as JSON |
synap providers
LLM providers on the pod (OpenAI/Anthropic/…) for local coding tools — not capability packs
synap providers [options] [command]synap providers list
Show enabled AI providers and their models
synap providers list [options]| Option | Description |
|---|---|
--json | Output as JSON |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
synap providers pull
Write pod LLM credentials into opencode or aider, or print the OpenAI-compatible {pod}/v1 endpoint
synap providers pull [options]| Option | Description |
|---|---|
--target <name> | Target tool: opencode | aider |
--pod-url <url> | Pod URL override |
--api-key <key> | API key override |
--show-key | With --target show: print the full API key (default: redacted) |
synap providers set-key
Store your own API key override for a provider (BYOI)
synap providers set-key [options] <providerId>| Option | Description |
|---|---|
--workspace <id> | Workspace ID for workspace-scoped override |
--api-key <key> | API key (prompted if omitted) |
--pod-url <url> | Pod URL override |
--hub-api-key <key> | Hub API key override |
synap providers list-keys
List user/workspace-level provider key overrides
synap providers list-keys [options]| Option | Description |
|---|---|
--workspace <id> | Workspace ID to check |
--pod-url <url> | Pod URL override |
--hub-api-key <key> | Hub API key override |
synap keys
Manage pod API keys
synap keys [options] [command]synap keys rotate
Rotate your CLI key to pick up the latest scope set
synap keys rotate [options]| Option | Description |
|---|---|
--show-key | Print the new key in full if it could not be saved to the config |
