cli.md

CLI Reference

Generated from the core and product CLI catalogs and explicit command contributions. This reference describes the full product; standalone core installations expose the locally composed subset through the same synergy command. Concept and lifecycle guidance lives in CLI guide; use synergy --help or synergy <command> --help for the exact options of the installed version.

Commands

Command	Description
acp	start ACP (Agent Client Protocol) server
agent	manage agents
auth	manage credentials
channel	manage messaging channels
config	manage synergy configuration
data	manage synergy data location and storage
debug	debugging and troubleshooting tools
desktop	open the installed Synergy Desktop application
diagnostics	create a local diagnostics package
doctor	diagnose synergy sandbox and environment
embed	manage the local embedding model
environment	manage compute on an attached server; print JSON results
export	export a session transcript or self-contained rollout ZIP
generate	generate the OpenAPI contract
holos	manage Holos identity and runtime
import	import a session transcript or rollout ZIP
install	install components, presets, plugins or applications
library	manage library memory and learning
list	list installed packages and legacy plugins
logs	show synergy background service logs
mcp	manage MCP (Model Context Protocol) servers
migrate	move synergy data to a new location (alias for 'data move')
migration	manage schema and data migrations
models	list all available models
plugin	install, remove, update, and inspect plugins
remove	remove packages and unused dependencies
secrets	manage the secret vault
send	send a message to synergy
server	start synergy server
session	manage sessions
start	start synergy background service
stats	show token usage and cost statistics
status	show synergy background service status
stop	stop synergy background service
uninstall	uninstall synergy and remove all related files
update	update explicitly installed packages
upgrade	upgrade synergy to the latest or a specific version
web	URL of a running synergy server
workspace	manage durable files on an attached server; print JSON results

acp

start ACP (Agent Client Protocol) server

Option	Description
--cwd (string)	working directory

add

add an MCP server

add [type]

add a channel configuration (writes to global config)

Option	Description
--print (boolean)	print config instead of writing to file

add

install and activate a plugin

agent

manage agents

agent

show agent configuration details

approve

review and approve the current plugin artifact

auth

manage credentials

auth [name]

authenticate with an OAuth-enabled MCP server

build [path]

build a plugin definition into an installable package

cancel

request cancellation of an existing process and drain its result

channel

manage messaging channels

check

verify stored objects and historical snapshot roots

clean

reclaim unowned legacy snapshot directories (dry-run unless --apply)

compact

pack shared snapshots (dry-run unless --apply)

config

manage synergy configuration

connect [name]

connect an MCP server on the running synergy server

create

create a new agent

Option	Description
--path (string)	directory path to generate the agent file
--description (string)	what the agent should do
--mode (string)	agent mode
--tools (string)
--model (string)	model to use in the format of provider/model

create

scaffold a definePlugin() project

Option	Description
--template (string)

create

create an object-backed Workspace without allocating compute

Option	Description
--name (string)	display name for this Workspace

credentials

show local Holos credential status

Option	Description
--json (boolean)	output as JSON

data

manage synergy data location and storage

debug

debugging and troubleshooting tools

debug

debug OAuth connection for an MCP server

delete

delete a session using recovery-safe filesystem/index cleanup

Option	Description
--scope (string)	scope id when the session index is missing
--yes (boolean)	confirm deletion
--json (boolean)

desktop

open the installed Synergy Desktop application

detach

save and detach an idle Workspace view

Option	Description
--revision (number)	observed Workspace revision

dev [path]

watch, rebuild, and atomically reload a plugin generation

Option	Description
--server-url (string)	isolated Synergy server URL for live reload

diagnostics

create a local diagnostics package

Option	Description
--startup (boolean)	create bounded startup diagnostics without opening any database
--session (string)	include indexed observability events for a specific session
--since (string)	include indexed observability events since a duration like 30m, 2h, or 7d
--output (string)	path for the generated .tar.gz package

diagnostics

get diagnostics for a file

diff

show diff for a snapshot hash

Option	Description
--session (string)

doctor

diagnose plugin config, lockfile, and cache drift

Option	Description
--fix (boolean)	repair duplicate config specs, stale lock entries, and orphan archive caches
--json (boolean)	output machine-readable JSON

document-symbols

get symbols from a document

download

download the local embedding model (used when no remote embedding API is configured)

embed

manage the local embedding model

embedding

configure embedding provider (writes to global config)

Option	Description
--print (boolean)	print config instead of writing to file

entry

generate a marketplace registry entry JSON

Option	Description
--repo (string)	plugin GitHub repository URL
--download-url (string)	release asset URL for the .synergy-plugin.tgz
--signature-url (string)	release asset URL for the .sig file
--release-backend (string)	release asset URL backend
--release-url-template (string)
--release-tag-template (string)
--write-entry (string)	write or update a marketplace plugins/.json entry
--changelog (string)	version changelog

environment

manage compute on an attached server; print JSON results

Option	Description
--attach (string)	target Synergy HTTP server URL
--scope (string)	Scope ID on the target server
--token-env (string)	environment variable containing the server bearer token

export

export config as JSONC (secrets redacted by default)

Option	Description
--include-secrets (boolean)	Include plaintext api keys and secrets in the export
--only (array)	Export only this domain; can be repeated
--scope (string)	Export global or current project config
--output (string)	Write to this file instead of stdout

export [sessionID]

export a session transcript or self-contained rollout ZIP

Option	Description
--format	export format
--run (string)	root run ID to include in the rollout
--output (string)	destination file (required for rollout ZIP)

export

export the observed saved files; does not include unsaved live changes

Option	Description
--revision (number)	observed Workspace revision

file

file system debugging utilities

files

list files using ripgrep

Option	Description
--query (string)
--glob (string)
--limit (number)

holos

manage Holos identity and runtime

import

import a session transcript or rollout ZIP

import

verify an archive and publish its files as a new Workspace

Option	Description
--name (string)	display name for the imported Workspace

import

import config from URL or file

Option	Description
--only (array)	Import only this domain; can be repeated
--mode (string)	Import merge mode
--scope (string)	Import into global or current project config
--dry-run (boolean)	Show import plan without writing files
--force (boolean)	Apply even if config changed after planning
--yes (boolean)	Apply without confirmation

info

show detailed plugin status and metadata

inspect

show snapshot ownership and logical/allocated storage usage

inspect

inspect allocation, leases and retained operations

inspect

inspect a session without hydrating its messages

Option	Description
--scope (string)	scope id when the session index is missing
--json (boolean)

install [spec..]

install components, presets, plugins or applications

Option	Description
--trust-host-code (boolean)	trust the resolved component and application code to run with host privileges
--approve-plugin (array)	approve the displayed API4 capability grant for these plugin ids
--resume (boolean)	finish an interrupted plugin activation

learning

configure experience learning parameters (writes to global config)

Option	Description
--print (boolean)	print config instead of writing to file

library

manage library memory and learning

list

list durable Workspaces and their current bindings

list

list files in a directory

login

bind to Holos platform

Option	Description
--agent-id (string)	optional expected Holos agent ID when importing a secret
--agent-secret (string)	log in with an existing Holos agent secret

login [url]

log in to a provider

logout

clear Holos credentials and stop the runtime

logout [name]

remove OAuth credentials for an MCP server

logs

show synergy background service logs

Option	Description
--tail (number)	number of trailing lines to show
--follow (boolean)	follow the log output
--level (string)	filter by log level (DEBUG, INFO, WARN, ERROR)
--service (string)	filter by service name
--grep (string)	filter lines matching pattern
--archive (number)	read a specific archive by index (0 = most recent)
--dev (boolean)	read the local development log instead of daemon logs
--trace-id (string)	filter observability events by trace id
--session (string)	filter observability events by session id
--tool-call (string)	filter observability events by tool call id
--since (string)	filter observability events since a duration like 30m, 2h, or 7d
--json (boolean)	print observability events as JSON

logs

show plugin runtime logs

lsp

LSP debugging utilities

mcp

manage MCP (Model Context Protocol) servers

memory

configure memory parameters (writes to global config)

Option	Description
--print (boolean)	print config instead of writing to file

merge

merge data from another synergy directory or zip archive

migrate

move synergy data to a new location (alias for 'data move')

Option	Description
--target (string)	target directory path
--remove-original (boolean)	remove original data after successful move
--dry-run (boolean)	show plan without executing

migration

manage schema and data migrations

Option	Description
--maintenance (boolean)	include optional blocking database maintenance; requires an idle maintenance window
--dry-run (boolean)	show what would run without executing

models [provider]

list all available models

Option	Description
--verbose (boolean)	use more verbose model output (includes metadata like costs)
--refresh (boolean)	refresh the models cache from models.dev

move

move synergy data to a new location

Option	Description
--remove-original (boolean)	remove original data after successful move
--dry-run (boolean)	show plan without executing

operations

list unfinished Workspace mutations

pack [output]

pack synergy data into a zip archive

pack [path]

package a built plugin

pack-legacy

pack all local legacy snapshot objects without deleting history or requiring a storage upgrade

patch

show patch for a snapshot hash

Option	Description
--session (string)

path

show config file paths

paths

show global paths (data, config, cache, state)

permissions

show declared plugin capabilities in user-language format

plugin

install, remove, update, and inspect plugins

preview [path]

build and watch a plugin in an isolated real Synergy host

Option	Description
--host-command (array)	host executable and arguments (defaults to installed synergy)

profiles

list configured compute and storage profiles without allocating compute

publish-market [tarball]

prepare and open an official Synergy Plugin Marketplace PR

Option	Description
--path (string)	plugin directory (defaults to cwd)
--repo (string)	plugin GitHub repository URL
--registry-dir (string)	local checkout path for the marketplace registry repository
--registry-repo (string)	registry repository to clone when --registry-dir does not exist
--registry-github-repo (string)	GitHub owner/repo used for opening the registry PR
--registry-base-branch (string)	base branch for the registry PR
--registry-branch-prefix (string)	branch prefix for registry PR branches
--download-url (string)	release asset URL for the .synergy-plugin.tgz
--signature-url (string)	release asset URL for the .sig file
--skip-release-upload (boolean)	do not create/upload GitHub Release assets
--release-backend	release asset backend; github can create/upload releases, manual only writes registry metadata
--release-url-template (string)
--release-tag-template (string)
--registry-branch (string)	exact registry branch name to use instead of the default generated branch
--registry-branch-template (string)
--registry-pr-title (string)
--registry-pr-body (string)
--pr (boolean)	open a PR after preparing registry changes; pass --no-pr to skip
--changelog (string)	version changelog for the registry entry

read

read file contents as JSON

reconcile

check the selected allocation without replaying commands

reconnect

reload the Holos runtime connection

recover

reconcile an existing operation and retry saving its result

Option	Description
--file (boolean)	recover a file mutation instead of process execution

recover

reconcile an existing Workspace mutation without replaying effects

recover-saved

copy the saved version to a new Workspace; retain unknown work on the original

Option	Description
--name (string)	display name for the recovered Workspace
--revision (number)	observed source Workspace revision

reencode

detect experience candidates with low-quality intent or script

Option	Description
--db (string)	path to library.db (defaults to global data dir)
--limit (number)	max candidates to show
--intent (boolean)	show intent candidates
--script (boolean)	show script candidates

register

register a secret value (read from a hidden prompt)

Option	Description
--policy-tools (array)	Restrict which tools may resolve this secret; can be repeated

register

register a directory on the target server's native host

release

save mounted files and release idle compute

Option	Description
--generation (number)	observed allocation generation

remove

remove a secret; historical mask tokens stop resolving

remove <name..>

remove explicitly installed packages and unused dependencies

repair

repair broken session indexes without deleting readable message data

Option	Description
--dry-run (boolean)	show planned repairs without applying them
--apply (boolean)	apply repairs
--json (boolean)

rerank

configure rerank provider (writes to global config)

Option	Description
--print (boolean)	print config instead of writing to file

restart [name]

restart an MCP server on the running synergy server

restart

restart plugin runtime

retry-install

retry a failed or pending lifecycle.install for a plugin

reveal

print a secret's plaintext to this terminal (local process only; never over HTTP)

rg

ripgrep debugging utilities

rotate

replace a secret's value; policy and history carry over

runtime

manage plugin runtime lifecycle

scrap

list all known projects

search

search file contents using ripgrep

Option	Description
--glob (array)
--limit (number)

search

search the npm registry for Synergy plugins

secrets

manage the secret vault

select

change Session compute independently of its Workspace

Option	Description
--expected	currently observed Environment ID, or none

select

change Session files independently of its Environment

Option	Description
--generation (number)	required binding generation when selecting a Workspace

send [message..]

send a message to synergy

Option	Description
--command (string)	the command to run, use message for args
--continue (boolean)	continue the last session
--session (string)	session id to continue
--scope (string)	registered scope id (defaults to the current directory, registering it when needed)
--model (string)	model to use in the format of provider/model
--agent (string)	agent to use
--experiment (string)	Versioned experiment configuration file
--non-interactive (boolean)	Fail explicitly if the task requires user input or permission
--timeout (number)	Task timeout in seconds, including descendants and cleanup
--format (string)	format: default (formatted) or json (raw JSON events)
--file (string)	file(s) to attach to message
--title (string)	title for the session (uses truncated prompt if no value provided)
--attach (string)	attach to a running synergy server (start one with: synergy start)
--port (number)	accepted for compatibility; local execution does not open an HTTP listener
--variant (string)	model variant (provider-specific reasoning effort, e.g., high, max, minimal)
--workflow (string)	run the message as a Light Loop workflow task: the session enables loop_stop and a reviewer loop, and send exits when the workflow reaches a terminal state

session

manage sessions

set-home

set SYNERGY_HOME to change data location (does not move data)

Option	Description
--unset (boolean)	remove SYNERGY_HOME, revert to default ~/.synergy

show

show current library configuration

sign

sign a plugin package tarball

Option	Description
--stdout (boolean)	also print the signature JSON to stdout

skill

list all available skills

snapshot

snapshot debugging utilities

snapshots

inspect and maintain file snapshot storage

start

start synergy background service

Option	Description
--non-interactive (boolean)	skip Holos login prompts before starting the background service

start [key]

start or reconnect channels

stats

show token usage and cost statistics

Option	Description
--run (string)	Show one run and its descendant accounting
--compare (string)	Compare two runs without inferring task quality
--days (number)	show stats for the last N days (default: all time)
--tools (number)	number of tools to show (default: all)
--models	show model statistics (default: hidden). Pass a number to show top N, otherwise shows all
--project (string)	filter by project (default: all projects, empty string: current project)
--recompute (boolean)	force full recompute from scratch
--json (boolean)	output raw JSON instead of formatted display

status

show synergy background service status

Option	Description
--verbose (boolean)	show lock, health, observability, and local process details

status

show plugin runtime status

stop

stop synergy background service

stop [key]

stop channels

stop

stop plugin runtime

storage

inspect, verify, recover, restore backups, and move authoritative Agent storage

Option	Description
--json (boolean)	print only the final status as JSON
--target (string)	JSONC configuration file containing the target storage domain; credentials use an environment reference

symbols

search workspace symbols

test [path]

run plugin tests

track

track current snapshot state

Option	Description
--session (string)

tree

show file tree using ripgrep

Option	Description
--limit (number)

tree [dir]

show directory tree

typegen [path]

generate UI operation and event types from plugin schemas

update [id]

update plugins to their latest version

Option	Description
--auto-approve (boolean)	auto-approve permission changes without prompting (low-security convenience)

update [name..]

update explicitly installed packages (all when no name is given)

Option	Description
--trust-host-code (boolean)	trust the resolved component and application code to run with host privileges
--approve-plugin (array)	approve the displayed API4 capability grant for these plugin ids

usage [provider]

show provider account usage and quota windows

validate [path]

validate definePlugin() source and generated artifacts

Option	Description
--runtime-discovery (boolean)	verify packaged runtime handlers

verify

verify stored Holos credentials

web

URL of a running synergy server

Option	Description
--attach (string)	URL of a running synergy server

wizard

interactive config wizard — auto-detect and set up providers

workspace

manage durable files on an attached server; print JSON results

Option	Description
--attach (string)	target Synergy HTTP server URL
--scope (string)	Scope ID on the target server
--token-env (string)	environment variable containing the server bearer token