CLI Reference

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

Commands

`init`

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

agentsync init [OPTIONS]

Options:

-p, --path <PATH>: Project root directory (defaults to current dir). Also supports --project-root alias.
-f, --force: Overwrite existing configuration without prompting.
-w, --wizard: Run interactive configuration wizard to migrate existing files.

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:

Scan your project for existing agent-related files — including instruction files (CLAUDE.md, .windsurfrules, OPENCODE.md, 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.)
Interactively prompt you to select which files to migrate
For instruction files: Read their content and merge into .agents/AGENTS.md
For skill directories: Copy contents into .agents/skills/ (with collision detection — duplicates are skipped with a warning)
For command directories: Copy contents into .agents/commands/
For MCP configs: Note their existence and suggest manual migration to [mcp_servers] in agentsync.toml
For other agent files (e.g., .cursor/): Copy to the .agents/ directory
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
Generate a configuration (.agents/agentsync.toml) that manages these files with symlinks
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
Optionally create backups of original files (after user confirmation, only for files that were copied)

`apply`

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

agentsync apply [OPTIONS]

Options:

-p, --path <PATH>: Project root directory. Also supports --project-root alias.
-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.
-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: Disable automatic .gitignore updates.

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

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

Examples:

# With default_agents = ["copilot", "claude"] in config:
agentsync apply              # Runs only copilot and claude
agentsync apply --agents gemini  # Runs only gemini (CLI overrides config)
agentsync apply --agents copilot,claude,gemini  # Runs all three

# Without default_agents in config:
agentsync apply              # Runs all enabled agents

`clean`

Removes all symbolic links managed by AgentSync.

agentsync clean [FLAGS]

Flags:

-p, --path <PATH>: Path to the project root. Also supports --project-root alias.
-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`

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

agentsync skill [OPTIONS] <COMMAND>

Global Options:

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

`install`

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

agentsync skill install [OPTIONS] <SKILL_ID>

--source <SOURCE>: Optional source (dir, archive, or URL).
--json: Output machine-readable JSON.

`update`

Update a skill to the latest version.

agentsync skill update [OPTIONS] <SKILL_ID>

--source <SOURCE>: Optional source (dir, archive, or URL).
--json: Output machine-readable JSON.

`uninstall`

Uninstall a skill.

agentsync skill uninstall <SKILL_ID>

`list`

List all installed skills.

agentsync skill list

`doctor`

Run diagnostic and health check for the synchronization environment.

agentsync doctor [OPTIONS]

Options:

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

Diagnostics:

Validates agentsync.toml existence and syntax.
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`

Shows the current version of the AgentSync CLI.

agentsync --version

`--help`

Shows help information for the CLI or a specific command.

agentsync --help
agentsync apply --help

Global Flags

-v, --verbose: Enable verbose logging for debugging purposes.
-q, --quiet: Only output errors.

`status`

Verify the status of symlinks managed by AgentSync and report drift.

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

Flags:

--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.
For each target it reports:
- destination: Path in the project where the symlink should exist
- exists: Whether the destination path exists
- is_symlink: Whether the destination is a symlink
- points_to: The symlink target (if any)
- expected_source: The resolved expected source path if the source exists

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

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:
- agentsync status
JSON for CI:
- agentsync status --json
With custom project root:
- agentsync status --project-root /path/to/repo --json