CLI Reference
August 28, 2026 · View on GitHub
Generated from the CLI registration in packages/synergy/src/main.ts. 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 |
browser | diagnose and install Chromium for Browser tools |
channel | manage messaging channels |
config | manage synergy configuration |
data | |
debug | debugging and troubleshooting tools |
diagnostics | create a local diagnostics package |
doctor | diagnose synergy sandbox and environment |
embed | manage the local embedding model |
export | |
generate | |
holos | manage Holos identity and runtime |
import | |
library | manage library memory and learning |
logs | show synergy background service logs |
mcp | manage MCP (Model Context Protocol) servers |
migrate | |
migration | manage schema and data migrations |
models | |
plugin | install, remove, update, and inspect plugins |
send | |
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 | |
upgrade | |
web | URL of a running synergy server |
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
browser
diagnose and install Chromium for Browser tools
channel
manage messaging channels
config
show resolved configuration
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 |
credentials
show local Holos credential status
| Option | Description |
|---|---|
--json (boolean) | output as JSON |
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) |
diagnostics
create a local diagnostics package
| Option | Description |
|---|---|
--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 |
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 session data as JSON
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 session data from JSON or JSON.GZ export file
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
inspect a session without hydrating its messages
| Option | Description |
|---|---|
--scope (string) | scope id when the session index is missing |
--json (boolean) |
install
install verified managed Chromium for Browser tools
| Option | Description |
|---|---|
--force (boolean) | reinstall Chromium even when the managed version is current |
--json (boolean) | print the installation result as JSON |
--deps (boolean) | install required Linux system packages (use --no-deps to skip) |
install-deps
install Linux system packages required by Chromium
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 sessions
| Option | Description |
|---|---|
--max-count (number) | limit to N most recent sessions |
--format (string) | output format |
--with-health (boolean) | include recovery-safe health data |
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 |
migration
manage schema and data migrations
| Option | Description |
|---|---|
--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 |
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
read
read file contents as JSON
reconnect
reload the Holos runtime connection
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 |
remove
uninstall and deactivate a plugin
| Option | Description |
|---|---|
--force (boolean) | skip confirmation prompt |
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
restart plugin runtime
retry-install
retry a failed or pending lifecycle.install for a plugin
rg
ripgrep debugging utilities
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
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 |
--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) | port for the local server (defaults to random port if no value provided) |
--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
show
show current library configuration
skill
list all available skills
snapshot
snapshot debugging utilities
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 |
|---|---|
--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
symbols
search workspace symbols
track
track current snapshot state
| Option | Description |
|---|---|
--session (string) |
tree
show file tree using ripgrep
| Option | Description |
|---|---|
--limit (number) |
tree [dir]
show directory tree
update [id]
update plugins to their latest version
| Option | Description |
|---|---|
--auto-approve (boolean) | auto-approve permission changes without prompting (low-security convenience) |
usage [provider]
show provider account usage and quota windows
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