Skip to content
AgentSync

CLI Reference

agentsync provides a straightforward set of commands to manage your AI agent configurations.

If you run AgentSync from Windows and need symlink prerequisites, WSL setup positioning, or recovery help, use the Windows Symlink Setup guide. The command reference below stays focused on CLI behavior.

Commands

Section titled “Commands”

init

Section titled “init”

Initializes a new AgentSync configuration in the current or specified directory.

Terminal window
agentsync init [OPTIONS]

Options:

  • -p, --path <PATH>: Project root directory (defaults to current dir). Also aliased as --project-root.
  • -f, --force: Overwrite existing configuration without prompting.
  • -w, --wizard: Run interactive configuration wizard to migrate existing files.
  • --experimental-tui: Run the init wizard with an experimental full-screen TUI intro. Requires --wizard.

Actions:

  • Creates the .agents/ directory if it doesn’t exist.
  • Creates a default .agents/agentsync.toml file.
  • Creates a template .agents/AGENTS.md file.

Wizard Mode: When using the --wizard flag, AgentSync will guide you through the same initialization flow described in the Getting Started guide, and this section provides the detailed, step‑by‑step reference for that wizard:

  1. Scan your project for existing agent-related files — including instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .windsurfrules, AMPCODE.md, etc.), skill directories (.claude/skills/, .cursor/skills/, .codex/skills/, .gemini/skills/, .opencode/skills/, .roo/skills/, .factory/skills/, .vibe/skills/, .agent/skills/), command directories (.claude/commands/, .gemini/commands/, .opencode/command/), MCP configs (.cursor/mcp.json, .windsurf/mcp_config.json, .roo/mcp.json, etc.), and agent directories (.cursor/, .windsurf/, etc.)
  2. Interactively prompt you to select which files to migrate
  3. For instruction files: Read their content and merge into .agents/AGENTS.md
  4. For skill directories: Copy contents into .agents/skills/ (with collision detection — duplicates are skipped with a warning)
  5. For command directories: Copy contents into .agents/commands/
  6. For MCP configs: Note their existence and suggest manual migration to [mcp_servers] in agentsync.toml
  7. For other agent files (e.g., .cursor/): Copy to the .agents/ directory
  8. For each migrated skills target, explicitly ask whether it should use symlink or symlink-contents, recommend symlink, and preserve an already-correct directory symlink by default
  9. Generate a configuration (.agents/agentsync.toml) that manages these files with symlinks
  10. Run a post-init validation summary that warns if a selected skills target is configured with symlink-contents while the destination is already a directory symlink to .agents/skills
  11. Optionally create backups of original files (after user confirmation, only for files that were copied)

apply

Section titled “apply”

Applies the configuration from agentsync.toml by creating symbolic links and updating .gitignore.

In workflow terms, agentsync apply reconciles your local managed destinations and then follows the repository’s gitignore policy:

  • default workflow: writes or updates the AgentSync-managed .gitignore block
  • committed-destination opt-out workflow: removes a stale AgentSync-managed block when [gitignore].enabled = false
  • temporary CLI opt-out: skips all .gitignore reconciliation when --no-gitignore is present

For the full team decision guide, see Gitignore Team Workflows. For install-time and Git hook automation patterns around apply, see Git Hook Automation.

If apply fails because the local Windows environment cannot create symlinks yet, fix the shell/setup prerequisites first with the Windows Symlink Setup guide.

Terminal window
agentsync apply [OPTIONS]

Options:

  • -p, --path <PATH>: Project root directory. Also aliased as --project-root.
  • -c, --config <CONFIG>: Use a custom configuration file path instead of the default .agents/agentsync.toml.
  • --clean: Deletes existing symbolic links before applying.
  • --dry-run: Shows what actions would be taken without actually making any changes, including pending .gitignore writes or cleanup when gitignore reconciliation is active.
  • -v, --verbose: Enable verbose logging.
  • -a, --agents <AGENTS>: Filter by agent (comma-separated list, e.g., claude,copilot). Overrides default_agents in config.
  • --no-gitignore: Strictly opt out of .gitignore reconciliation for that invocation. AgentSync will not write, update, or remove its managed .gitignore block, even if config would otherwise do so.

Agent Selection Priority: When running agentsync apply, agents are selected in this order:

  1. --agents flag (if provided) → runs only specified agents
  2. default_agents in config (if set and no --agents) → runs only agents in the list
  3. All enabled agents (if neither above is set) → runs all agents with enabled = true

Examples:

With default_agents = ["copilot", "claude"] in config:

Terminal window
npx @dallay/agentsync apply

Runs only copilot and claude.

Terminal window
npx @dallay/agentsync apply --agents gemini

Runs only gemini (CLI overrides config).

Terminal window
npx @dallay/agentsync apply --agents copilot,claude,gemini

Runs all three.

Without default_agents in config:

Terminal window
npx @dallay/agentsync apply

Runs all enabled agents.

Preview symlink and gitignore reconciliation:

Terminal window
npx @dallay/agentsync apply --dry-run

Skip gitignore reconciliation for this run only:

Terminal window
npx @dallay/agentsync apply --no-gitignore

Preview without any gitignore writes or cleanup:

Terminal window
npx @dallay/agentsync apply --dry-run --no-gitignore

clean

Section titled “clean”

Removes all symbolic links managed by AgentSync.

Terminal window
agentsync clean [FLAGS]

Flags:

  • -p, --path <PATH>: Path to the project root. Also aliased as --project-root.
  • -c, --config <PATH>: Path to a custom configuration file.
  • --dry-run: Shows what would be removed without actually deleting anything.
  • -v, --verbose: Enable verbose logging.

skill

Section titled “skill”

Manage installable AI agent skills from skills.sh/other providers.

Terminal window
agentsync skill [OPTIONS] <COMMAND>

Global Options:

  • -p, --project-root <PROJECT_ROOT>: Root of the project (defaults to CWD).

install

Section titled “install”

Install a skill from skills.sh or a custom provider.

Terminal window
agentsync skill install [OPTIONS] <SKILL_ID>
  • --source <SOURCE>: Optional source (dir, archive, or URL).
  • --json: Output machine-readable JSON.

suggest

Section titled “suggest”

Suggest repository-aware skills without installing them.

Terminal window
agentsync skill suggest [--json] [--install [--all]]
  • --json: Output detections, recommendations, and summary counts as JSON.
  • --install: Start the recommendation-driven install flow.
  • --all: Use with --install to install every not-yet-installed recommendation without prompting.

Behavior:

  • skill suggest is read-only by default.
  • Detection scope currently supports 110+ technologies. See the Skills guide for a representative list.
  • Detection comes from Rust repository scanning, while recommendation mapping comes from AgentSync’s curated catalog.
  • Recommendations are opinionated, not exhaustive.
  • The runtime loads an embedded declarative catalog first, then optionally overlays valid provider metadata.
  • One detected technology may map to multiple recommended skills.
  • Combo catalog entries are supported in schema and loading, but active combo evaluation is currently deferred.
  • --install opens an interactive selector in a TTY.
  • --install --all is the explicit non-interactive path and installs every not-yet-installed recommendation.
  • Recommendation-driven installs reuse the same install pipeline and registry updates as skill install, and they skip recommendations that are already installed.

Compatibility note:

  • Catalog metadata can carry canonical provider skill ids internally.
  • Current CLI output, installation, and installed-state tracking still use local slug-like skill_id values.
  • Direct skill install <SKILL_ID> therefore continues to expect the current local/runtime id shape.

Examples:

Terminal window
npx @dallay/agentsync skill suggest
Terminal window
npx @dallay/agentsync skill suggest --json
Terminal window
npx @dallay/agentsync skill suggest --install
Terminal window
npx @dallay/agentsync skill suggest --install --all

update

Section titled “update”

Update a skill to the latest version.

Terminal window
agentsync skill update [OPTIONS] <SKILL_ID>
  • --source <SOURCE>: Optional source (dir, archive, or URL).
  • --json: Output machine-readable JSON.

uninstall

Section titled “uninstall”

Uninstall a skill.

Terminal window
agentsync skill uninstall [OPTIONS] <SKILL_ID>
  • --json: Output machine-readable JSON.

list

Section titled “list”

List all installed skills.

[!NOTE] The list command is currently not implemented.

Terminal window
agentsync skill list

doctor

Section titled “doctor”

Run diagnostic and health check for the synchronization environment.

Terminal window
agentsync doctor [OPTIONS]

Options:

  • -p, --project-root <PROJECT_ROOT>: Project root (defaults to CWD).

Diagnostics:

  • Validates agentsync.toml existence and syntax.
  • Verifies target source existence — checks that all files or directories referenced as sources in your configuration actually exist.
  • Detects configuration anomalies — warns if a target is misconfigured (e.g., a module-map target with no mappings).
  • Detects destination conflicts.
  • Audits .gitignore with marker-aware parsing.
  • Verifies MCP server executability.
  • Detects unmanaged Claude skills — warns if .claude/skills/ contains content that isn’t managed by any configured target in agentsync.toml.
  • Detects recognized skills mode mismatches — warns when a skills target is configured as symlink-contents but the destination already is the expected directory symlink, so apply would cause avoidable churn.

--version

Section titled “--version”

Shows the current version of the AgentSync CLI.

Terminal window
npx @dallay/agentsync --version

--help

Section titled “--help”

Shows help information for the CLI or a specific command.

Terminal window
npx @dallay/agentsync --help
Terminal window
npx @dallay/agentsync apply --help

status

Section titled “status”

Verify the status of AgentSync-managed targets and report drift.

Terminal window
agentsync status [--project-root <path>] [--json]

Flags:

  • -p, --project-root <path>: Optional. Path to the project root to locate the agentsync config. If omitted, the current working directory is used.
  • --json: Output machine-readable JSON (pretty-printed) describing each managed target. Useful for CI.

Behavior:

  • Iterates over all enabled agents and their targets from your agentsync.toml.
  • Validates each target according to its configured sync type.
    • symlink checks the destination path itself as the managed symlink.
    • symlink-contents checks the destination as a managed directory container plus the expected child symlinks inside it.
  • For each target it reports additive machine-readable fields such as:
    • destination: Path in the project where the managed target lives
    • sync_type: The configured sync mode for that target
    • destination_kind: Whether the destination currently resolves to a symlink, directory, file, or is missing
    • exists: Whether the destination path exists
    • is_symlink: Whether the destination itself is a symlink
    • points_to: The symlink target (if any)
    • expected_source: The resolved expected source path for single-link targets when the source exists
    • issues: Structured drift reasons
    • managed_children: Child-level detail for symlink-contents targets

Human-friendly output uses colors and statuses:

  • ✔ OK — symlink exists and points to the expected source
  • ✗ Incorrect link — symlink exists but points somewhere else
  • ! Missing — destination does not exist
  • · Exists but not a symlink — a regular file or directory exists at the destination

For symlink-contents, success output identifies the destination as a managed container directory. A valid empty source such as .agents/commands/ with zero eligible files is still reported as OK, and the destination directory is not treated as missing or “not a symlink” solely because it currently has 0 managed entries expected.

If a skills target is otherwise healthy but its configured mode disagrees with a recognized existing layout (for example symlink-contents configured while the destination is already the expected directory symlink), status keeps the entry as OK and prints a focused hint instead of treating it as broken.

Exit codes

  • 0 — no problems detected
  • 1 — one or more issues found (suitable to fail CI builds)

Examples

  • Human readable:
    • Terminal window
      npx @dallay/agentsync status
  • JSON for CI:
    • Terminal window
      npx @dallay/agentsync status --json
  • With custom project root:
    • Terminal window
      npx @dallay/agentsync status --project-root /path/to/repo --json

On Windows, status is also a practical post-setup verification step after you fix symlink permissions or switch to WSL. See the Windows Symlink Setup guide for the broader verification flow.