CLI commands

At a glance

Command	Purpose	Key flags / args
`init [<git-url>]`	Create `~/.agentsync/`; optionally clone a bootstrap repo. `--scope project` / `--project <path>` scaffolds a project tree instead.	`--scope --project`
`doctor`	Diagnose setup: PATH, home/state writability, schema, secrets backend.
`verify`	Validate config; surface unresolved `${secret:}` / `${env:}` refs. `--scope project` / `--project <path>` lints the project tree instead.	`--scope --project`
`agent add\|remove\|list\|enable\|disable <name>`	Manage the agent registry — the user’s, or a project tree’s own `[agents]` declaration with `--scope project` / `--project <path>`.	`disable --purge --scope --project`
`mcp add\|remove\|list <name>`	Manage MCP servers.	`--type --command --args --url --env --agents`
`marketplace add\|remove\|list <url-or-name>`	Manage marketplaces.
`plugin install\|upgrade\|enable\|disable\|remove\|list <id>`	Manage plugins.	`install <id[@marketplace]>`
`secrets set\|get\|edit <key>`	Manage age-encrypted secrets.	`set --stdin`
`update`	(network) Refresh marketplace cache + pins.	`--apply --auto-safe --scope --project`
`apply`	Render source → write agent configs (offline). Git-versions each destination dir (opt-out).	`--dry-run --scope --project --no-git-backup`
`revert <agent>`	Roll a destination dir back to a prior apply checkpoint (local-only git history).	`--to --all --dry-run`
`status`	Summarize drift / pending across agents (skill dirs collapse by default).	`--agents --verbose --json --scope --project`
`diff [<path>]`	Show pending / drift changes; secrets redacted.	`--scope --project`
`reconcile`	Interactively merge drift back into source.	`--auto-writeback --auto-override --auto-safe --scope --project`
`import <agent>[:<component>[:<name>]]`	Capture native config into source. `--scope project` captures the agent’s native project-scope config into the project tree.	`--dry-run --scope --project`
`explain [<plugin>...]`	Show per-agent translation coverage for one or more plugins.	`--all --list --json`
`version`	Print version information (alias for `--version`).

Setup & diagnostics

`init [<git-url>]`

Creates the ~/.agentsync/ directory and its layout (user scope). Pass a git URL to clone an existing bootstrap config instead of starting empty (user scope only).

--scope project scaffolds a project source tree at <cwd>/.agentsync/ instead — the same on-disk layout as the user tree (agentsync.toml plus mcp/, lsp/, skills/, agents/, commands/, hooks/, memory/ with fragments/, plugins/, secrets/), but no .state/ (apply records state centrally under ~/.agentsync/.state/, keyed by project root). --project <path> targets <path>/.agentsync/ and implies project scope; --scope user together with --project is an error. Commit the .agentsync/ tree to share project agent config with collaborators. Full guide: Project-local config.

`doctor`

A health check: verifies your PATH, that home and state directories are writable, that the config schema parses, and that the secrets backend is reachable. It also lists plugins installed natively in an agent (Claude) that aren’t in your source yet — run import <agent>:plugin to capture them. Run it first when something feels off.

`verify`

Validates the canonical config and surfaces every unresolved ${secret:…} / ${env:…} reference. Ideal for CI — see Verify config in CI. Pair with AGENTSYNC_ALLOW_OFFLINE_VERIFY=1 on runners without an age key.

Defaults to user scope. --scope project (walks up from cwd to the .agentsync/ tree) or --project <path> schema-lints the project source tree and validates its references — resolving ${secret:…} against the inherited user secrets backend, exactly as apply does, so the two never disagree. With no scope flag inside a project tree the choice is ambiguous: verify prompts project-vs-user, or fails closed under --no-input / a non-TTY stdin.

Building your config

`agent`

Manage which agents agentsync applies to.

agentsync agent add claude        # register
agentsync agent list              # registry + enabled state
agentsync agent list --all        # every supported agent (registered or not)
agentsync agent disable opencode  # stop applying (keeps source)
agentsync agent disable opencode --purge   # also remove what it wrote

Every subcommand also takes --scope project / --project <path> to manage the project’s own [agents] declaration in <root>/.agentsync/agentsync.toml — the set project scope renders to (user-scope agents are never inherited; see Project-local config):

agentsync agent add claude --scope project     # declare a project agent
agentsync agent list --project ~/code/myrepo   # read a project's declaration
agentsync agent disable claude --purge --scope project  # purge only this project's rendered files

`mcp`

Manage MCP servers. Full guide: MCP servers.

agentsync mcp add github --command npx --args "-y,@modelcontextprotocol/server-github"
agentsync mcp add linear --type http --url https://mcp.linear.app/sse
agentsync mcp list
agentsync mcp remove github

Flags: --type (stdio|http|sse), --command, --args, --url, --env, --agents.

`marketplace` & `plugin`

Manage plugin registries and the plugins drawn from them. Full guide: Marketplaces & plugins.

agentsync marketplace add github:anthropics/claude-plugins-official
agentsync plugin install atlassian@anthropic
agentsync plugin list

`secrets`

Manage the age-encrypted vault. Full guide: Secrets.

agentsync secrets set github.token --stdin
agentsync secrets get github.token
agentsync secrets edit

The apply / capture loop

`apply`

Renders the source and writes each agent’s native config. Offline — it never touches the network. --dry-run runs the full pipeline and prints the plan and translation report without writing a byte; each planned destination is labeled ✓ synced (already holds our exact bytes) or → write (would be created or changed), with a — N to write, M already synced tally, so an in-sync tree reads as a no-op rather than a list of pending writes.

agentsync apply --dry-run
agentsync apply

Destination git backup. After a successful user-scope apply that changes managed files, apply keeps each agent’s destination dir (~/.claude, ~/.codex, …) in its own local-only git repo and records a checkpoint commit, so a bad apply is one agentsync revert away. The first apply to an untracked dir prompts to enable this (opt-out); answer once and it’s remembered in [destination_directory_git_backup]. These repos are never pushed (the history may hold cleartext secrets, like the files it versions — which is why it stays local). A dir already under your own source control is left untouched. Pass --no-git-backup to skip it for one run (CI/scripting) without touching config. The [destination_directory_git_backup] table (mode = "prompt" | "on" | "off", optional author_name/author_email) controls the default; agentsync doctor shows the current mode and per-dir status. See agentsync revert below.

`revert <agent>`

Rolls an agent’s destination dir back to a prior apply checkpoint from its local-only git history — recovering from a bad apply. It is append-only: it records a new commit, so the history is never rewritten and the revert is itself revertible. By default it undoes the most recent apply (restores the previous checkpoint); --to <ref> picks a specific one (a commit hash or HEAD~2), --all reverts every managed dir, and --dry-run previews the file changes without writing.

revert moves only the destination. The next apply re-renders from the canonical source and would overwrite the reverted state, so revert prints a notice telling you to reconcile (agentsync reconcile / import) or fix the canonical source first. Only agentsync-managed (git-backed) user-scope dirs can be reverted.

agentsync revert claude              # undo the most recent apply to ~/.claude
agentsync revert claude --to HEAD~3  # roll back further
agentsync revert --all --dry-run     # preview reverting every managed dir

`status`

Summarizes what’s out of sync across all agents — pending source changes and destination drift. To stay readable, each skill directory collapses to one row by default (the skill dir, its most-severe drift class, and a faint SKILL.md + N files count — with a per-class breakdown when the bundled files don’t all share one class), so a skill shipping hundreds of assets no longer floods the report. Pass -v/--verbose to expand every skill back to one row per bundled file. A one-line summary footer tallies items by drift class, and a brief “What apply will do:” legend follows it, explaining each class present (new will be created, pending will be updated to match source, drift will be overwritten — use reconcile to keep the edit, etc.). Clean items are tallied but never glossed.

Use --agents <list> (a comma-separated allowlist, matching mcp add --agents; * = all enabled) to scope the report — agentsync status --agents claude shows just Claude Code. Orphaned-state warnings still consider the full enabled set, so narrowing the view never mislabels a deselected agent as an orphan.

Pass --json to emit the structured drift report (per-agent items + a summary tally keyed by drift class) for CI gates or dashboards; advisory diagnostics still flow to stderr so the JSON payload stays clean. --json is never collapsed — it carries every tracked file regardless of the human view — and omits the legend (the class field is the machine contract).

`diff [<path>]`

Shows the pending / drift changes in detail. Resolved secrets are redacted, so a piped diff can’t leak credentials. Pass a path to scope the diff. Color is TTY-gated — piped output uses [-…-] / {+…+} text markers instead of raw ANSI. Pass --json for a structured hunk list (the same masked source/dest strings, so the redaction protects both modes).

`reconcile`

The interactive merge UX for drift and conflicts. Full guide: The daily loop. Non-interactive flags: --auto-writeback, --auto-override, --auto-safe.

`import <agent>[:<component>[:<name>]]`

Captures native config back into your canonical source. Drop parts of the selector to widen scope. The plugin component (Claude only in v1) captures installed plugins + their marketplaces by re-fetching them into the agentsync cache, so a real plugin import uses the network. A plugin’s marketplace is resolved from agentsync’s own registered marketplaces first, then the agent’s native config; a plugin whose marketplace is registered in neither (e.g. a built-in like claude-plugins-official you have not yet marketplace added) is reported and skipped.

--scope project (optionally --project <path>) reads the agent’s native project-scope config (e.g. <root>/.claude/) and captures it into the project source tree <root>/.agentsync/ instead of your user tree, seeding central state with the project scope + root so the next apply doesn’t foreign-collide. Plugin import is user-scope only: a named import claude:plugin:<name> --scope project errors, and a bulk import claude:plugin --scope project silently skips (plugins are a user-scope concept across the harnesses). Full guide: Already have configs?.

`update`

The main networked verb. Refreshes the marketplace cache and recomputes version pins, then optionally applies. (import’s plugin component also reaches the network, to re-fetch the plugins it captures.) Full guide: Updating from the network.

agentsync update
agentsync update --apply --auto-safe

`explain [<plugin>...]`

Prints per-agent translation coverage for one or more installed plugins, without applying. Pass space-separated plugin ids to explain just those, --all to explain every installed plugin, or --list to print just the set of installed ids (a quick reminder of what you can pass). A ◐ partial row’s trailing note is split by kind — (N reduced · M dropped) — so it never reads as “N whole components discarded”: a reduced part still rendered, just without some fields the agent has no home for, while a dropped part had no native target and was not emitted. Each part is itemized beneath a framing header, tagged reduced or dropped with its reason, so the tally is never a dead end. Add --json for machine-readable output (rows for plugin/agent coverage — each with a skipDetails array of {component, name, reason, kind}, where kind is "reduced" or "dropped" and component is the plain kind — or a plugins array under --list).

agentsync explain atlassian@anthropic
agentsync explain atlassian@anthropic superpowers@obra
agentsync explain --all
agentsync explain --list

Flags that work across commands

Flag	Applies to	Effect
`--scope user\|project`	init, verify, import, apply, status, diff, reconcile, update	Force the config scope.
`--project <path>`	init, verify, import, apply, status, diff, reconcile, update	Target / apply a specific project’s tree.
`--dry-run`	apply, import	Preview without writing.
`--auto-safe`	reconcile, update	Auto-resolve only no-risk changes.
`--json`	status, diff, explain	Emit the structured payload to stdout (advisory diagnostics still go to stderr). `explain --list --json` emits a `plugins` array; `explain` with ids/`--all` emits the translation `rows`.
`--agents <list>`	status	Scope the report to a comma-separated agent allowlist (`*` = all enabled; matches `mcp add --agents`).
`--color auto\|always\|never`	all	Control ANSI color + bold. Default `auto` (on for a TTY, off when piped/redirected; honors `NO_COLOR`).
`-v`, `--verbose`	all	Verbose logging. In `status`, also expands each collapsed skill directory back to one row per bundled file.
`--version`	root	Print version information and exit. The `agentsync version` subcommand is an alias.

CLI commands

At a glance

Setup & diagnostics

init [<git-url>]

doctor

verify

Building your config

agent

mcp

marketplace & plugin

secrets

The apply / capture loop

apply

revert <agent>

status

diff [<path>]

reconcile

import <agent>[:<component>[:<name>]]

update

explain [<plugin>...]