SynapSynapDocs

CLI

Every command of @synap-core/cli, generated from its command definitions.

For BuildersCLIGenerated from Synap-core/synap-cli@7562355c1 (main)

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

FileContents
~/.synap/credentials.jsonYour Synap account token.
~/.synap/config.jsonSaved pods: URL, workspace, agent identity and key. (Older versions used pod-config.json.)

Never commit them.

VariableDefault
SYNAP_CP_URLhttps://api.synap.live
SYNAP_LANDING_URLhttps://synap.live

Commands

220 commands, grouped by top-level command. 5 hidden commands (internal or deprecated) are not listed.

Global optionDescription
-V, --versionoutput 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]
OptionDescription
--pod-url <url>Synap pod URL (skip pod choice prompt)
--api-key <key>Hub Protocol API key (skip key generation)
-y, --yesAccept the defaults, no prompts (connects the agents found on this machine)
--agents <list>Agents to connect, comma-separated: claude-code,codex,cursor
--jsonPrint 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 connected

synap launch

Stand up a NEW company/OS on a pod — creates a project + its core workspaces (interactive)

synap launch [options]
OptionDescription
--listList 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)
--jsonOutput 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]
OptionDescription
--toolTreat <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)
--listList what can be connected and exit
--with-mcpRaycast 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>
OptionDescription
--surface <surface>Only switch this surface (raycast, claude-code, claude-desktop, cursor)
--jsonOutput 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]
OptionDescription
--url <url>New pod URL (alternative to the positional arg)
--yesNon-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]
OptionDescription
--jsonDump 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]
OptionDescription
--jsonOutput as JSON
--fixFix key problems: finish a pending approval, give this computer its own key, or rewrite stale copies — then verify over MCP
-v, --verboseEvery 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]
OptionDescription
--jsonOutput structured {artifacts:[...]} JSON

synap whoami

Show key owner vs EFFECTIVE user (+ isAgent), scopes/workspace, and flag env-vs-surface key divergence

synap whoami [options]
OptionDescription
--jsonOutput 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]
OptionDescription
--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)
--jsonOutput 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]
OptionDescription
--workspace <id>Scope to a specific workspace
--jsonOutput 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]
OptionDescription
--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]
OptionDescription
--offSwitch 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]
OptionDescription
--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]
OptionDescription
--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]
OptionDescription
--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]
OptionDescription
--cp-url <url>Control-plane origin override (default: derived from the pod host)
--jsonOutput 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>
OptionDescription
--name <name>Pod profile to use (default: active)
--workspace <id>Scope to a specific workspace
--project <id>Focus the agent on a project
--jsonOutput as JSON

synap login

Connect your Synap account (private templates) + your pods

synap login [options]
OptionDescription
--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]
OptionDescription
--jsonOutput as JSON
--detailsInclude 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]
OptionDescription
--workspace <id|name>Workspace to digest (defaults to active workspace lens)
--project <id|name>Project to digest (cross-cutting lens)
--jsonOutput 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]
OptionDescription
--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
--jsonOutput 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>
OptionDescription
--sessionEphemeral: scope only this Claude Code session, don't persist
--globalDurable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json
--jsonOutput 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]
OptionDescription
--jsonOutput 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>
OptionDescription
--description <text>Optional one-line description
--jsonOutput 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>
OptionDescription
--sessionEphemeral: scope only this Claude Code session, don't persist (cross-pod refs refused)
--globalDurable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json
--jsonOutput 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]
OptionDescription
--sessionEphemeral: clear only this Claude Code session's project
--jsonOutput as JSON

synap project purge

HARD teardown: delete a project + its pod-wide-exclusive entities (owner-only, irreversible)

synap project purge [options] <target>
OptionDescription
--confirm <name>Confirm non-interactively by passing the exact project name
--yesSkip the interactive name prompt (uses the resolved name)
--jsonOutput 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]
OptionDescription
--jsonOutput 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>
OptionDescription
--workspace <id>Scope to a specific workspace (omit for pod-wide)
--limit <n>Max results per substrate Default: "10".
--jsonOutput as JSON
--sessionScope retrieval to the active session context
--rawSkip synthesis: show the raw per-substrate matches instead
--compareA/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]
OptionDescription
--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
--sessionLink captured knowledge to the active session
--pod-wideGLOBAL lane: pod-wide cross-cutting runbook (→ knowledge_keys), visible in every workspace
--globalAlias for --pod-wide
--key <ns:slug>Stable key for a --pod-wide runbook (derived from --type + --claim if omitted)
--teamPin 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
--yesSkip the y/N confirmation prompt (smart mode)
--jsonOutput as JSON

synap import

Import files, folders, or URLs into the pod (AI capture pipeline, or Superwhisper store-first)

synap import [options] [inputs...]
OptionDescription
--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-runPreview only — do not write
--yesSkip confirmation / auto-confirm store-first
--sessionLink created entities to the active session
--jsonOutput 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-firstSkip AI structure; store units as pod-wide notes (+ optional audio)
--keep-rawKeep the original file and link it to the created entity (default: extract, then discard the bytes)
--with-audioUpload WAV provenance (default on for --source superwhisper --store-first)
--no-with-audioTranscript-only (no WAV upload)
--limit <n>Max Superwhisper units to process
--concurrency <n>Parallel unit uploads (1–4)
--no-resumeIgnore 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>
OptionDescription
--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
--openOpen in the Synap desktop app after upload
--jsonOutput 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 --open

synap subscribe

Stream pod events as NDJSON (long-poll)

synap subscribe [options]
OptionDescription
--event <pattern>Filter by event type pattern (e.g. proposal.*)
--limit <n>Events per poll Default: "20".
--jsonNDJSON 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]
OptionDescription
--workspace <id>Workspace to read (defaults to active workspace)
--jsonOutput 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]
OptionDescription
--repo <name>Filter knowledge by repo tag
--limit <n>Entries per section Default: "5".
--jsonNDJSON 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]
OptionDescription
--jsonOutput as JSON (default: human-readable)
--profilesShow only profiles (use with --json for machine-readable schema)
--commandsShow only the command tree
--summaryList 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>
OptionDescription
--sessionEphemeral: scope only this Claude Code session, don't persist
--globalDurable machine-wide default (~/.synap/config.json) instead of this directory's .synap/lens.json
--jsonOutput 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--sessionEphemeral: clear only this Claude Code session's workspace
--jsonOutput as JSON

synap workspace provision-agent

Provision an agent-owned workspace and set it as active (idempotent)

synap workspace provision-agent [options]
OptionDescription
--agent-user-id <uuid>Agent user ID (defaults to caller)
--name <name>Workspace display name override
--no-useDo not set as active workspace after provisioning
--jsonOutput as JSON

synap workspace purge

HARD teardown: delete a workspace + all its entities and blobs (owner-only, irreversible)

synap workspace purge [options] <target>
OptionDescription
--confirm <name>Confirm non-interactively by passing the exact workspace name
--yesSkip the interactive name prompt (uses the resolved name)
--jsonOutput 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>
OptionDescription
--reason <text>Why — shown to the reviewer
--jsonOutput 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>
OptionDescription
--reason <text>Why — shown to the reviewer
--jsonOutput 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>
OptionDescription
--jsonOutput 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...>
OptionDescription
--to <workspace>Destination workspace id or name Required.
--reason <text>Why they belong there — shown to the reviewer
--jsonOutput 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--workspace <id>Workspace (defaults to active)
--jsonOutput as JSON

synap list views

List views in a workspace (whiteboard, kanban, bento, …)

synap list views [options]
OptionDescription
--type <type>Filter by view type (e.g. whiteboard, kanban, calendar)
--workspace <id>Workspace (defaults to active)
--jsonOutput 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]
OptionDescription
--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".
--jsonOutput 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>
OptionDescription
--jsonOutput 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>
OptionDescription
--property <kv>Role property as key=value (repeatable) Default: [].
--workspace <id>Role's lens (defaults to the active workspace)
--jsonOutput 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>
OptionDescription
--jsonOutput 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]
OptionDescription
--entity <id>Entity id (with --role, resolves the facet to detach)
--role <slug>Role slug (with --entity)
--jsonOutput 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]
OptionDescription
--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".
--jsonOutput 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>
OptionDescription
--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
--yesAccepted for symmetry with other commands, but does NOT skip the typed confirmation — approval is always deliberate
--jsonOutput 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>
OptionDescription
--reason <text>Rejection reason
--jsonOutput 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>
OptionDescription
--timeout <duration>Give up after this long (e.g. 30m, 2h) Default: "30m".
--interval <duration>Delay between checks (e.g. 10s) Default: "10s".
--jsonOutput 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]
OptionDescription
--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".
--onceCheck 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-permissionsLaunch with --dangerously-skip-permissions instead of an allow-list
--dry-runClaim 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]
OptionDescription
--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-templateOpt 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[])
--jsonOutput 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]
OptionDescription
--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".
--jsonOutput 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>
OptionDescription
--workspace <id>Workspace hint if the pod still requires it for GET
--jsonOutput 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>
OptionDescription
--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
--jsonOutput 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>
OptionDescription
--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)
--jsonOutput 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>
OptionDescription
--jsonOutput 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--jsonOutput as JSON

synap session evidence

Post your own pass/fail report for one evidence-checked acceptance criterion

synap session evidence [options] <key>
OptionDescription
--session <id>Focus session ID (defaults to this terminal's active session)
--passedThe criterion is satisfied
--failedThe criterion is not satisfied
--detail <text>Optional note explaining the verdict
--jsonOutput 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]
OptionDescription
--session <id>Focus session ID (defaults to this terminal's active session)
--jsonOutput 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>
OptionDescription
--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".
--jsonOutput 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>
OptionDescription
--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
--jsonOutput 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]
OptionDescription
--project <id>Project id (defaults to the active project lens)
--allInclude archived tracks
--jsonOutput 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>
OptionDescription
--jsonOutput 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]
OptionDescription
--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
--jsonOutput 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>
OptionDescription
--reason <text>Why — shown to the reviewer
--jsonOutput 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>
OptionDescription
--reason <text>Why — shown to the reviewer
--jsonOutput 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...>
OptionDescription
--reason <text>Why — shown to the reviewer
--jsonOutput 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>
OptionDescription
--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)
--jsonOutput 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]
OptionDescription
--session <id>Focus session ID (required)
--workspace <id>Workspace ID (defaults to active workspace)
--jsonOutput 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>
OptionDescription
--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>
OptionDescription
--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>
OptionDescription
--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

OptionDescription
--pod-url <url>Pod URL override
--api-key <key>API key override
--debugShow resolved credentials

synap skill approve

Approve a skill so it loads (agent-authored skills are born unapproved)

synap skill approve [options] <slug-or-id>
OptionDescription
--revokeRevoke 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

OptionDescription
--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]
OptionDescription
--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]
OptionDescription
--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.
--jsonOutput 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]
OptionDescription
--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".
--jsonOutput 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>
OptionDescription
--category <cat>working_style | communication | focus | technical | preference Default: "preference".
--confidence <n>Confidence score 0-1 Default: "0.5".
--jsonOutput 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>
OptionDescription
--category <cat>Filter by category
--limit <n>Max results Default: "10".
--jsonOutput 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>
OptionDescription
--workspace <id>Workspace context
--jsonOutput 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]
OptionDescription
--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: "{}".
--jsonOutput 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]
OptionDescription
--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
--jsonOutput 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>
OptionDescription
--props <json>Properties as JSON string Required.
--workspace <id>Workspace ID (sent in PATCH body so workspace-scoped automations fire)
--jsonOutput 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]
OptionDescription
--jsonOutput as JSON
--localList 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]
OptionDescription
--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-mcpRaycast 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]
OptionDescription
--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>
OptionDescription
--show-keyPrint the MCP URL and the full API key
--snippetsPrint 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>
OptionDescription
--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
--newStart 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)
--jsonMachine-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]
OptionDescription
--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
--newStart 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]
OptionDescription
--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-runPrint 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]
OptionDescription
--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-nowAlso run immediately after creating the schedule
--listList 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]
OptionDescription
--dry-runShow 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>
OptionDescription
--workspace <id|name>Workspace to use (uses active workspace/lens if omitted)
--thread <id>Continue an existing agent thread/channel
--newStart a fresh agent thread
--timeout <seconds>How long to wait for the agent's reply (default: 90)
--jsonMachine-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]
OptionDescription
--workspace <id>Workspace to scope the rule to (uses active workspace if omitted)
--pod-wideScope the rule to the whole pod, ignoring the active workspace
--yesSkip the one-off confirmation (never skips a clarification)
--jsonOutput 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]
OptionDescription
--workspace <id>Filter by workspace
--jsonOutput 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]
OptionDescription
--workspace <id>Filter by workspace
--status <status>Filter by status (active|draft|paused|error)
--jsonOutput raw JSON

synap automation describe

Show full details of an automation

synap automation describe [options] <id>
OptionDescription
--workspace <id>
--json

synap automation create

Create an automation (quick flags or --from file.yaml)

synap automation create [options]
OptionDescription
--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>
OptionDescription
--workspace <id>

synap automation disable

Pause an automation

synap automation disable [options] <id>
OptionDescription
--workspace <id>

synap automation delete

Delete an automation

synap automation delete [options] <id>
OptionDescription
--workspace <id>
--forceSkip confirmation prompt

synap automation schema

Fetch the automation DSL schema from the pod (AI context)

synap automation schema [options]
OptionDescription
--write-context [path]Write markdown context file for Claude Code
--jsonOutput 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]
OptionDescription
--entity <id>Start entity ID Required.
--depth <n>Traversal depth (max 3) Default: "2".
--jsonRaw 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--entity <id>Filter by entity ID (subjectId)
--limit <n>Number of events Default: "20".
--jsonRaw 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]
OptionDescription
--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
--jsonJSON 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]
OptionDescription
--type <type>Filter by view type (e.g. whiteboard, kanban, calendar)
--workspace <id>Workspace ID
--jsonJSON 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>
OptionDescription
--file <path>JSON file containing widget layout (array or { widgets: [...] })
--workspace <id>Workspace ID
--jsonJSON 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]
OptionDescription
--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
--openOpen in the Synap desktop app after creation
--jsonJSON 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>
OptionDescription
--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
--openOpen in the Synap desktop app after update
--jsonJSON 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.md

synap doc reference

Create an external reference document (points at a URL — no bytes stored)

synap doc reference [options] <url>
OptionDescription
--title <title>Document title Required.
--workspace <id>Workspace to create the reference in
--openOpen in the Synap desktop app after creation
--jsonJSON 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]
OptionDescription
--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
--openOpen in the Synap desktop app after define
--jsonJSON 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>
OptionDescription
--out <file>Output file path (default: <entry>.bundle.js)
--bundle-depsInline 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-containedBuild ONE complete HTML document (React, CSS, brand fonts inlined; nothing external) — the code of a rendererType "mcp-app" cell
--fontsWith --self-contained: require the inlined brand fonts (default: include when @synap-core/design-tokens resolves)
--no-fontsWith --self-contained: skip the inlined brand fonts
--defineChain 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)
--openOpen in browser after define (used with --define)
--jsonJSON 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-deps

synap 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]
OptionDescription
--html <file>HTML file to upload Required.
--name <name>Document title (default: filename)
--workspace <id>Workspace context
--openOpen in the Synap desktop app after creation
--jsonJSON 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]
OptionDescription
--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]
OptionDescription
--jsonOutput 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>
OptionDescription
--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>
OptionDescription
--workspace <id>Workspace context

synap tools disconnect

Revoke a tool's connection

synap tools disconnect [options] <provider>
OptionDescription
--workspace <id>Workspace context
--forceSkip confirmation

synap tools schema

Fetch tool schema and supported providers (AI context)

synap tools schema [options]
OptionDescription
--write-context [path]Write to .claude/TOOLS_CONTEXT.md
--jsonOutput 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]
OptionDescription
--jsonOutput the full structured graph as JSON
--orphansOnly 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>
OptionDescription
--template <slug>The template slug to adopt this workspace into Required.
--jsonOutput 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>
OptionDescription
--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)
--jsonOutput as JSON

synap vendor show

Show whether you have a publisher profile

synap vendor show [options]
OptionDescription
--jsonOutput as JSON

synap market

Browse + install packages (workspaces, capabilities, skills, workflows, views, cells) into a project

synap market [options] [command]
OptionDescription
--listList and exit (the default action)
--search <query>Filter by name/description/slug
--type <type>Filter by package type (workspace|capability|skill|workflow|view|cell)
--jsonOutput 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>
OptionDescription
--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-runPreview 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)
--jsonOutput 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...]
OptionDescription
--yesApply 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-runForce the preview path — never apply, even with --yes
--timeout <seconds>How long to wait for each package's apply to finish (default: 120)
--jsonOutput 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]
OptionDescription
--outdatedOnly show packages with an update available
--treeShow the composition graph — package → templates → resulting workspaces, marking shared nodes
--layersShow the composition graph as a flat DAG — one row per slug, bedrock-first, with true fan-in counts
--jsonOutput 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]
OptionDescription
--unattachedOnly show workspaces that need attention (unattached or missing a version stamp)
--jsonOutput 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>
OptionDescription
--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)
--jsonOutput 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>
OptionDescription
--kind <kind>Scaffold a standalone package instead of a workspace template: cell, view, workflow, capability, skill
--jsonOutput as JSON

synap market validate

Validate a local template file against the shared template validator — fast author feedback

synap market validate [options] <file>
OptionDescription
--jsonOutput 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...]
OptionDescription
--officialPublish 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-runWith --official: preview what would change against the live catalog, publish nothing
--yesWith --official: skip the confirmation prompt
--publicPublish as PUBLIC (default is private)
--privatePublish 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.
--jsonOutput 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-depsPublish 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>
OptionDescription
--jsonOutput 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]
OptionDescription
--needs-attentionShow only workspaces that need action (drifted / unstamped / unattached-with-suggestion)
--jsonOutput 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>
OptionDescription
--slug <slug>Force a specific template instead of the suggestion
--yesAccept 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)
--jsonOutput 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

OptionDescription
--yesApply 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-runPreview only — never apply
--timeout <seconds>How long to wait for each apply (default: 120)
--jsonOutput 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>
OptionDescription
--dry-runShow the plan only — move nothing
--yesMove without asking (for scripts)
--jsonOutput 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...]
OptionDescription
--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)
--jsonOutput as JSON

synap catalog diff

Show what would change against the live control-plane catalog (new / changed / unchanged)

synap catalog diff [options] [slugs...]
OptionDescription
--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)
--jsonOutput 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...]
OptionDescription
--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)
--jsonOutput as JSON
--officialPublish as the synap-official vendor (required)
--dry-runPreview the diff only — publish nothing
--yesSkip 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--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]
OptionDescription
--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

OptionDescription
--workspace <id>Workspace context
--forceSkip 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]
OptionDescription
--workspace <id>Workspace context

synap capability connect

Connect a service — omit the name to pick from connectable services

synap capability connect [options] [name]
OptionDescription
--workspace <id>Workspace context
--reconnectForce 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>
OptionDescription
--workspace <id>Workspace context
--forceSkip confirmation

synap capability show

Show one capability's full detail: status, connection, verbs, next action

synap capability show [options] <name>
OptionDescription
--jsonOutput as JSON
--workspace <id>Workspace context

synap capability run

Launch a verb — pass inputs as --key value flags

synap capability run [options] <verb> [params...]
OptionDescription
--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>
OptionDescription
--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>
OptionDescription
--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>
OptionDescription
--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)
--defaultMark 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>
OptionDescription
--label <label>New connection label
--value <value>New secret / credential value
--rotatePrompt (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
--defaultMark 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

OptionDescription
--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]
OptionDescription
--workspace <id>Workspace context
--jsonOutput 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]
OptionDescription
--workspace <id>Workspace context
--jsonOutput 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]
OptionDescription
--jsonOutput 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]
OptionDescription
--target <name>Target tool: opencode | aider
--pod-url <url>Pod URL override
--api-key <key>API key override
--show-keyWith --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>
OptionDescription
--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]
OptionDescription
--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]
OptionDescription
--show-keyPrint the new key in full if it could not be saved to the config

On this page

Files and environmentCommandssynap initsynap launchsynap connectsynap podssynap pods listsynap pods addsynap pods usesynap pods updatesynap pods removesynap pods reconnectsynap statussynap doctorsynap versionssynap whoamisynap updatesynap switchsynap connectionssynap appsynap app initsynap app connectsynap mcpsynap mcp urlsynap mcp verifysynap mcp bridgesynap mcp use-bridgesynap mcp connectsynap mcp connect-chatgptsynap mcp connect-chatgpt-oauthsynap mcp connect-claudesynap mcp ui-setupsynap loginsynap orientsynap digestsynap diagnosesynap usesynap projectsynap project listsynap project newsynap project usesynap project clearsynap project purgesynap lenssynap asksynap capturesynap importsynap uploadsynap subscribesynap homesynap contextsynap discoversynap workspacesynap workspace usesynap workspace listsynap workspace clearsynap workspace provision-agentsynap workspace purgesynap workspace archivesynap workspace restoresynap workspace renamesynap entitysynap entity movesynap listsynap list workspacessynap list profilessynap list viewssynap list entitiessynap showsynap facetsynap facet attachsynap facet listsynap facet detachsynap proposalssynap proposals listsynap proposals approvesynap proposals rejectsynap proposals awaitsynap workersynap sessionsynap session startsynap session listsynap session getsynap session updatesynap session closesynap session attachsynap session detachsynap session currentsynap session evidencesynap session evaluatesynap session waitsynap playbooksynap playbook runsynap tracksynap track listsynap track showsynap track startsynap track advancesynap track statussynap track paramssynap track start-stepsynap skillsynap skill gather-contextsynap skill suggestsynap skill getsynap skill addsynap skill listsynap skill approvesynap skill removesynap skill syncsynap skill verify-codesynap browsesynap observesynap observe writesynap observe recallsynap getsynap get entitysynap createsynap create entitysynap create relationsynap setsynap set entitysynap agentssynap agents listsynap agents addsynap agents createsynap agents rotate-keysynap agents removesynap agents infosynap agentsynap agent asksynap agent chatsynap agent runsynap agent schedulesynap agent ticksynap automatesynap rulesynap rule listsynap automationsynap automation listsynap automation describesynap automation createsynap automation enablesynap automation disablesynap automation deletesynap automation schemasynap graphsynap centralitysynap centrality statussynap centrality recomputesynap eventssynap viewsynap view createsynap view listsynap view arrangesynap explainsynap opensynap docsynap doc createsynap doc updatesynap doc referencesynap cellsynap cell definesynap cell buildsynap artifactsynap artifact createsynap connect-servicesynap toolssynap tools listsynap tools connectsynap tools syncsynap tools disconnectsynap tools schemasynap podsynap pod adoptsynap vendorsynap vendor createsynap vendor showsynap marketsynap market installsynap market updatesynap market installedsynap market workspacessynap market attachsynap market scaffoldsynap market validatesynap market publishsynap market unpublishsynap templatessynap templates attachsynap templates updatesynap templates retiresynap catalogsynap catalog validatesynap catalog diffsynap catalog publishsynap capabilitysynap capability listsynap capability addsynap capability createsynap capability rmsynap capability enablesynap capability connectsynap capability disconnectsynap capability showsynap capability runsynap capability testsynap capability connectionssynap capability connections listsynap capability connections addsynap capability connections updatesynap capability connections rmsynap capability sync-statussynap syncsynap sync statussynap providerssynap providers listsynap providers pullsynap providers set-keysynap providers list-keyssynap keyssynap keys rotate