CLI Reference
August 28, 2026 · View on GitHub
The installed synergy CLI manages the product runtime and submits work to it. Source development uses the separate root bun dev orchestrator described in Development.
Run synergy --help or synergy <command> --help for the exact options supported by the installed version.
Global Options
| Option | Meaning |
|---|---|
-h, --help | Show command help |
-v, --version | Show the installed version |
--print-logs | Mirror runtime logs to stderr |
--log-level DEBUG|INFO|WARN|ERROR | Override the configured log level for this process |
completion | Generate a shell completion script |
Runtime Modes
| Command | Ownership and lifetime |
|---|---|
synergy start | Install/start a managed background service through launchd, systemd user services, or Windows Task Scheduler |
synergy server | Run the server in the current foreground terminal; bare synergy is an alias for this command |
synergy web | Open the Web UI served by an already running runtime |
synergy send ... | Attach to a runtime when --attach is supplied; otherwise start a private ephemeral local server for the command |
These modes share data and configuration when they use the same SYNERGY_HOME, but only one persistent server process may own that home at a time. A private send server stops when its task reaches idle.
Background service
synergy start
synergy status
synergy status --verbose
synergy logs --follow
synergy stop
start runs the first-time configuration wizard in an interactive terminal when no config exists. --non-interactive skips first-run and Holos prompts. Existing services report config drift; stop and start again to install changed network settings into the service definition.
The managed service defaults to 127.0.0.1:4096. --hostname, --port, --mdns, and repeatable --cors override the corresponding server config for the installed service invocation. Each explicit --cors value authorizes both cross-origin HTTP requests and Browser viewer WebSocket handshakes from that exact HTTP(S) origin. Automatically detected LAN CORS origins and reverse-proxy forwarding headers do not authorize Browser viewer sockets, so pass the public Browser viewer Origin explicitly.
status --verbose adds runtime-lock, health, process, listening-port, trace, and local process-registry information. stop manages only the installed background service; do not use it as a generic process killer for an unrelated foreground server.
Foreground server
synergy server
synergy server --hostname 127.0.0.1 --port 4097
The foreground command defaults its CLI hostname to 0.0.0.0. Port 0 asks the server to prefer 4096 and fall back to an available ephemeral port. Global server configuration applies unless a network option is explicit. Use an explicit loopback hostname when the runtime should not accept LAN connections.
The server lock reports the existing PID, mode, working directory, command, health, and listening ports when another server already owns the same Synergy home.
Web
synergy web
synergy web --attach http://localhost:4097
web does not start a server. It verifies /global/health, verifies that the target serves the Web application, and opens the authenticated attach URL. The default target is http://localhost:4096.
One-off Work with send
synergy send "Summarize this project"
synergy send --scope home "Summarize recent work"
synergy send --scope <scope-id> "Continue work in that project"
synergy send --attach http://localhost:4096 "Continue the work"
synergy send --agent synergy-max --model provider/model "Fix the failing test"
synergy send --file report.pdf --file src "Review these inputs"
printf 'extra context' | synergy send "Use stdin too"
Important options:
| Option | Meaning |
|---|---|
--attach <url> | Use a running server instead of a private ephemeral server |
--scope <id> | Use the registered home or project Scope ID; unknown or archived IDs fail without creation |
-c, --continue | Continue the latest top-level session in the selected Scope |
-s, --session <id> | Continue a specific session |
--agent <name> | Select a primary agent; subagent names are rejected as primary choices |
-m, --model <provider/model> | Override the model |
--variant <name> | Select provider-specific reasoning/model variant |
-f, --file <path> | Attach a file or directory; repeatable |
--command <name> | Run a configured Synergy command, using the message as arguments |
--title [text] | Set the new-session title; an empty value derives it from the prompt |
--workflow lightloop | 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 |
--format default|json | Render progress for humans or emit newline-delimited event JSON |
--port <number> | Port for the private local server; omitted means an available port |
When --scope is omitted, send uses the launch directory (or SYNERGY_CWD). An existing directory is resolved and registered as a project Scope when needed, even if Synergy has not opened it before; a missing directory resolves to the home Scope. Pass --scope to select an already registered Scope without registering the launch directory. With --attach, the target runtime owns and validates the Scope ID.
Piped stdin is appended to the prompt. The command subscribes to session events before prompting, renders completed tools and terminal text, and handles interactive guarded permission requests with allow-once or reject choices.
Configuration, Providers, and Models
| Command family | Purpose |
|---|---|
synergy config path | Print config, data, and cache roots |
synergy config wizard | Detect providers and write core model configuration |
synergy config import <file-or-url> | Preview or apply domain-aware config import |
synergy config export | Export config as JSONC (secrets redacted by default) |
synergy config embedding | Configure an embedding provider |
synergy config rerank | Configure a rerank provider |
synergy auth login|logout|list|usage | Manage provider credentials and inspect supported usage windows |
synergy models [provider] | List available configured models |
synergy agent create|list | Create or inspect agent definitions |
synergy mcp add|list|auth|logout|debug | Configure, authenticate, and inspect MCP servers |
synergy embed download | Download the local embedding model assets |
config import
synergy config import <source> imports JSON or JSONC configuration from a local file path or an HTTP(S) URL. Sources are limited to 1 MiB; URL fetches time out after 15 seconds and reject redirects. The command produces a domain-aware plan, shows value-level changes, and asks for confirmation before applying.
synergy config import ./settings.jsonc
synergy config import https://example.com/config.json --dry-run
synergy config import ./config.jsonc --scope project --only models --only providers
synergy config import ./config.jsonc --mode replace-domain --yes
| Option | Meaning |
|---|---|
--scope global|project | Target scope; defaults to global; project scope requires an active project |
--only <domain> | Import only the named domain; repeatable for multiple domains |
--mode merge|replace-domain|append | Override the per-domain default merge policy |
--dry-run | Show the plan without writing files |
--force | Apply even when config changed after planning (stale revision) |
--yes, -y | Skip the confirmation prompt |
All domains are importable and default to merge mode. append recursively merges objects and appends arrays in source order; imported scalar values override existing values. Conflicts and hardcoded secrets are flagged as warnings without blocking. A stale plan (config changed between plan and apply) is rejected unless --force is supplied.
JSONC comments in existing domain files are preserved. Committed files trigger a runtime config reload; reload failure does not roll back the committed changes.
config export
synergy config export writes the merged config at the target scope as JSONC to stdout or a file. Secrets are replaced with the __REDACTED__ sentinel by default; pass --include-secrets to keep plaintext values — a warning is printed to stderr either way, and files written with --output are chmod'd 0600. A redacted export can be re-imported later — the import merges the sentinel with the stored secret (see Configuration Layout: Config Export).
synergy config export > backup.jsonc
synergy config export --scope project --only providers --only models
synergy config export --include-secrets -o full-backup.jsonc
| Option | Meaning |
|---|---|
--include-secrets | Keep plaintext secrets; files written with this flag get 0600 permissions |
--only <domain> | Export only the named domain; repeatable for multiple domains |
--scope global|project | Source scope; defaults to global; project scope requires an active project |
--output, -o | Write to this file instead of stdout |
Export semantics worth knowing:
- Export is read-only. A domain file that fails to parse is skipped and reported as a warning on stderr (the API result carries the same
warnings) — it is not quarantined or moved aside. {env:VAR}and{file:path}references are resolved when the file is read, so the export contains resolved values. Re-importing such an export writes those values back as plaintext; if you rely on env-indirection, re-add the{env:}references after importing (see Configuration Layout: Config Export).- Relative
pluginspecs are exported relative to the config directory, keeping the payload machine-independent. Plugin directories themselves often differ between machines, so re-check plugin paths after a cross-machine import. - The HTTP API (
GET /config/export) is always redacted:includeSecrets=trueis rejected with 400. Plaintext export is CLI-only.
The openai-codex provider uses ChatGPT/Codex OAuth credentials and the Codex backend. The openai provider uses OpenAI Platform API-key credentials. The grok provider uses xAI subscription OAuth credentials (SuperGrok / X Premium+) against the OpenAI-compatible https://api.x.ai/v1 API. Their login, storage, usage, and billing semantics are intentionally separate. The Grok model list is discovered live from the xAI /v1/language-models API with the stored subscription OAuth credential and refreshes automatically (≤1h TTL, or via synergy models --refresh); offline or failed discovery falls back to the bundled list.
See Configuration for files, precedence, domains, and instruction discovery.
embed download
synergy embed download fetches the bundled local embedding model (Xenova/all-MiniLM-L6-v2, ~80 MB) so that embedding calls start instantly. The command is for local mode; when a remote embedding API key is configured it exits immediately with "No download needed."
synergy embed download
The command displays:
- the model name, size, and purpose
- the configured download source (Hugging Face Hub, HF Mirror, or custom)
- live byte and percentage progress, updated roughly every 250 ms
- success confirmation with the final "ready" message
On failure, the command prints the error and suggests troubleshooting steps: check the network connection, verify the configured download source in embedding.local.source, or configure a remote embedding API with synergy config embedding.
The download source is set in 00-general.jsonc under embedding.local.source ("huggingface", "hf-mirror", or "custom"). The custom source requires embedding.local.remoteHost to be a public HTTPS origin.
When source is "huggingface" (the default) and a download fails, Synergy automatically retries once from hf-mirror.com, then falls back to the on-disk cache. Explicit "hf-mirror" and "custom" sources skip the auto-fallback and go straight to the disk cache. Remote downloads abort with an error if no response bytes arrive within 30 seconds (time-to-first-byte), so an unreachable source fails with a clear message instead of hanging at 0%.
Model files are cached under ~/.synergy/data/embedding/models; customize the location with embedding.local.cacheDir.
See Knowledge: Embedding Model for the embedding lifecycle and Configuration: Embedding for the full config schema.
Sessions, Library, and Data
| Command family | Purpose |
|---|---|
synergy session list | List sessions for a Scope |
synergy session inspect <id> | Inspect one session |
synergy session delete <id> | Delete one session |
synergy session repair | Run session integrity/recovery repair |
synergy export [sessionID] | Export session data |
synergy import <file> | Import an exported session |
synergy library show|learning|memory|reencode | Inspect and maintain Library learning state |
synergy stats | Read or recompute installation-wide session, model, agent, tool, token, cost, code-change, and activity statistics |
synergy data path | Show the current Synergy home/data location |
synergy data pack [output] | Pack selected data categories |
synergy data merge <source> | Merge a data bundle into the current home |
synergy data move <target> | Move managed Synergy data |
synergy data set-home <path> | Set the configured data home |
synergy migrate [--target <path>] | Backward-compatible alias for the interactive data-move workflow |
synergy migration status|run|rollback|generate | Inspect and manage versioned schema/data migrations |
Use the data commands for supported relocation and merge workflows. Copying individual JSON files while the server is running can violate indexes and atomic update assumptions.
synergy stats --json emits the complete snapshot; --recompute rebuilds its derived digests and buckets, while --days, --tools, and --models change the displayed view. The accepted --project option currently recomputes but does not filter the installation-wide result. See Activity and Statistics.
Connections
| Command family | Purpose |
|---|---|
synergy channel add|list|start|stop|status | Configure and control Channel accounts |
synergy holos login|logout|status|verify|reconnect|credentials | Manage Holos identity and connection readiness |
synergy acp | Run the Agent Client Protocol integration |
Channel and Holos connection models are described in Connections.
Browser Installation and Diagnostics
synergy browser doctor
synergy browser doctor --json
synergy browser install
synergy browser install --force --json
synergy browser install --no-deps
synergy browser install-deps
browser doctor checks Chromium discovery, executable version, and an actual headless launch using the same arguments as Browser tools. On Linux it also reports dynamic-loader diagnostics. The command exits with status 1 when Browser is not ready; --json emits the complete structured report.
browser install downloads Chromium into Synergy-managed data without replacing system browsers. It accepts only a release manifest signed by Synergy, verifies the target, archive size, and SHA-256 digest, and installs atomically. Repeated installs reuse the current managed version; --force reinstalls it.
On Linux, browser install also installs the distribution packages required by the release's pinned Playwright version. This system-package step can invoke sudo or su; run it from an account authorized to install packages. Use --no-deps when those packages are managed separately, or run browser install-deps to repair only the system dependencies. JSON install reports include systemDependencies with installed, not-required, or skipped.
Local source builds do not have signed release manifests; use an installed release or set CHROMIUM_PATH. Unsupported platforms can also install Chrome or Chromium separately and set CHROMIUM_PATH.
Diagnostics and Maintenance
| Command | Purpose |
|---|---|
synergy doctor | Run installation and runtime health checks |
synergy diagnostics | Collect a redacted diagnostics bundle |
synergy logs [--follow] | Read the current log stream |
synergy debug ... | Developer inspection for config, agents, files, LSP, ripgrep, skills, snapshots, and paths |
synergy upgrade [target] | Upgrade the installed release |
synergy uninstall | Remove the installed product after confirmation/options |
synergy generate | Generate supported artifacts used by development/release workflows |
synergy doctor lists the current installation method, every detected installation channel (npm, yarn, pnpm, bun, desktop, or standalone) with its version and, where available, its executable, plus the synergy candidates on PATH. It exits nonzero when no supported installation is detected, when multiple channels coexist, or when an installed version cannot be verified. A PATH-first mismatch (the first synergy on PATH is not the current CLI) is reported as a warning. Homebrew's synergy formula is unrelated to this project and is not detected or managed.
synergy upgrade preserves the detected installation channel. Supported package-manager installations use their owning manager, Desktop installations defer to the Desktop updater, and standalone CLI installations rerun the official installer pinned to the requested release's vX.Y.Z GitHub tag. Standalone upgrades therefore require a published GitHub release tag and do not use an npm-only dev or preview version's installer. Override detection with --method <npm|yarn|pnpm|bun|desktop|standalone>; if multiple channels coexist and no override is provided, upgrade exits nonzero instead of guessing. Installer and package-manager warning checks are advisory and fail open, so probe failures do not block installation.
synergy uninstall removes the selected installation channel and, by default, the shared data, cache, config, and state directories; the existing --keep-data and --keep-config options still preserve the corresponding directories. Pass --installation-only to remove only the selected channel while preserving shared data, cache, config, and state. Use --method <npm|yarn|pnpm|bun|desktop|standalone> to select the channel when multiple are installed. Package-manager channels are removed through their owning package manager. Desktop removal cleans only the CLI link or Windows PATH entry and prints platform-specific app removal guidance. Standalone removal deletes only installer-owned runtime paths, preserves shared sandbox helpers and user data, removes all exact PATH entries written by the installer, and defers deletion of a running Windows executable until the process exits.
debug and migration commands are maintainer-oriented. Prefer stable product commands and APIs for application integrations.
Plugins
synergy plugin includes create, add, remove, retry-install, update, build, sign, pack, list, search, doctor, validate, dev, runtime, test, publish-market, entry, info, permissions, and approval commands. synergy plugin approve <id> fetches the server approval review for a configured plugin and submits the opaque reviewToken through POST /api/plugins/approve; it does not send manifest, capability, source, or path data. list and info show approval-disabled plugins with their canonical identity and Needs approval state. Installed plugins can also contribute their own top-level CLI commands. synergy plugin retry-install <id> re-queues a failed or pending lifecycle.install; the host delivers it at the next server start or plugin runtime reload. It errors instead when the plugin's lockfile generation no longer matches the installed generation — reinstall or update the plugin to retry in that case.
The canonical authoring and command reference is Plugin documentation.