Skip to content

docs: update CLI and configuration reference documentation #587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yacosta738 merged 2 commits into from
Sep 22, 2026
+37 −22
Merged

docs: update CLI and configuration reference documentation #587

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94cccc0
docs: update CLI and configuration reference documentation
yacosta738 Sep 5, 2026
40eb096
Merge branch 'main' into docs/plugin-and-compatibility-matrix-fixes-1…
yacosta738 Sep 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions website/docs/src/content/docs/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -330,6 +330,9 @@ Manage repository-owned, vendor-neutral plugin materialization.
agentsync plugin [OPTIONS] <COMMAND>
```

**Global Options**:
- `-p, --project-root <PROJECT_ROOT>`: Root of the project (defaults to CWD).

The project must declare the marketplace in `.agents/agentsync.toml`; `add` and `update` persist
the selected plugin in that file if it is not already present.

Expand All @@ -345,6 +348,9 @@ Resolve the configured marketplace reference, validate the selected plugin, writ
agentsync plugin add <MARKETPLACE/PLUGIN> [--json]
```

**Options**:
- `--json`: Output machine-readable JSON.

This is an explicit network-capable operation for Git sources. Local sources remain offline.
Git sources are snapshotted into AgentSync-owned project state. `plugin add` and `plugin update`
are the only commands that resolve `marketplace.reference` or write lock entries.
Expand All @@ -357,6 +363,9 @@ Resolve the configured reference again and replace the lock entry after validati
agentsync plugin update <MARKETPLACE/PLUGIN> [--json]
```

**Options**:
- `--json`: Output machine-readable JSON.

#### `list`

List locked plugins and their revisions without changing files.
Expand All @@ -365,6 +374,9 @@ List locked plugins and their revisions without changing files.
agentsync plugin list [--json]
```

**Options**:
- `--json`: Output machine-readable JSON.

#### `status`

Validate locked source content and report drift without materializing, downloading, or executing
Expand Down Expand Up @@ -401,6 +413,9 @@ matching selection from `agentsync.toml`. It also revokes all `allowed_mcp` appr
agentsync plugin remove <MARKETPLACE/PLUGIN> [--json]
```

**Options**:
- `--json`: Output machine-readable JSON.

Plugin MCP declarations are generated by the normal `agentsync apply` flow. They are namespaced as
`plugin/<marketplace>/<plugin>/<server>` and are never started by AgentSync.

Expand Down
44 changes: 22 additions & 22 deletions website/docs/src/content/docs/reference/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,41 +263,41 @@ The matrix below documents common agent locations and whether AgentSync can hand
| Agent | Rules File(s) | MCP Configuration / Notes | Skills Support / Location |
| :--- | :--- | :--- | :--- |
| AGENTS.md | `AGENTS.md` | Pseudo-agent pattern via `[agents.root]` target | - |
| GitHub Copilot | `.github/copilot-instructions.md` | `.vscode/mcp.json` (native MCP) | Configurable |
| Aider | - | No native MCP formatter; `.aider.conf.yml`, `.aiderignore` ignores | Configurable |
| Amazon Q CLI | - | No native MCP formatter; `.amazonq/rules/`, `.amazonq/mcp.json` ignores | Configurable |
| Amp | `AMPCODE.md` | No native MCP formatter | Configurable |
| Antigravity | - | No native MCP formatter; `.agent/rules/`, `.agent/skills/` ignores | Configurable |
| AugmentCode | - | No native MCP formatter; `.augment/rules/` ignore | Configurable |
| Claude Code | `CLAUDE.md` | `.mcp.json` (native MCP) | Configurable; `.claude/skills/` |
| Claude Desktop | - | Global config (native MCP); disabled by default | - |
| OpenAI Codex CLI | `AGENTS.md` | `.codex/config.toml` (native MCP) | Configurable; `.codex/skills/` |
| VS Code | - | `.vscode/mcp.json` (native MCP) | Configurable |
| Pi Coding Agent | - | No native MCP formatter | Configurable |
| Jules | - | No native MCP formatter | Configurable |
| Cursor | `.cursor/rules/agentsync.mdc` | `.cursor/mcp.json` (native MCP) | Configurable; `.cursor/skills/` |
| Windsurf | `.windsurfrules` | No native MCP formatter; `.windsurf/mcp_config.json` ignore | Configurable |
| Cline | `.clinerules` | No native MCP formatter | Configurable |
| Crush | `CRUSH.md` | No native MCP formatter; `.crush.json` ignore | Configurable |
| Amp | `AMPCODE.md` | No native MCP formatter | Configurable |
| Antigravity | - | No native MCP formatter; `.agent/rules/`, `.agent/skills/` ignores | Configurable |
| Amazon Q CLI | - | No native MCP formatter; `.amazonq/rules/`, `.amazonq/mcp.json` ignores | Configurable |
| Aider | - | No native MCP formatter; `.aider.conf.yml`, `.aiderignore` ignores | Configurable |
| Cursor | `.cursor/rules/agentsync.mdc` | `.cursor/mcp.json` (native MCP) | Configurable; `.cursor/skills/` |
| Factory Droid | - | No native MCP formatter; `.factory/mcp.json`, `.factory/skills/` ignores | Configurable |
| Firebase Studio | - | No native MCP formatter; `.idx/airules.md`, `.idx/mcp.json` ignores | Configurable |
| Open Hands | - | No native MCP formatter; `.openhands/microagents/` ignore | Configurable |

**Note (Cursor rules filename):** `.cursor/rules/agentsync.mdc` is the documented example path used by AgentSync for Cursor rules. You may use a different `.mdc` filename/path if you configure it explicitly under your `[agents.<name>.targets.*]` entries.
| Firebender | - | No native MCP formatter; `firebender.json` ignore | Configurable |
| Gemini CLI | `GEMINI.md` | `.gemini/settings.json` (native MCP, adds `"trust": true`) | Configurable; `.gemini/skills/` |
| GitHub Copilot | `.github/copilot-instructions.md` | `.vscode/mcp.json` (native MCP) | Configurable |
| Goose | - | No native MCP formatter; `.goosehints` ignore | Configurable |
| JetBrains AI Assistant | - | No native MCP formatter; `.aiassistant/rules/` ignore | Configurable |
| Jules | - | No native MCP formatter | Configurable |
| Junie | - | No native MCP formatter; `.junie/` ignore | Configurable |
| AugmentCode | - | No native MCP formatter; `.augment/rules/` ignore | Configurable |
| Kilo Code | - | No native MCP formatter; `.kilocode/mcp.json` ignore | Configurable |
| Kiro | - | No native MCP formatter; `.kiro/steering/`, `.kiro/settings/mcp.json` ignores | Configurable |
| Mistral Vibe | - | No native MCP formatter; `.vibe/config.toml`, `.vibe/skills/` ignores | Configurable |
| Open Hands | - | No native MCP formatter; `.openhands/microagents/` ignore | Configurable |
| OpenAI Codex CLI | `AGENTS.md` | `.codex/config.toml` (native MCP) | Configurable; `.codex/skills/` |
| OpenCode | `AGENTS.md` | `opencode.json` (native MCP) | Configurable; `.opencode/skills/` |
| Goose | - | No native MCP formatter; `.goosehints` ignore | Configurable |
| Pi Coding Agent | - | No native MCP formatter | Configurable |
| Qwen Code | - | No native MCP formatter; `.qwen/settings.json` ignore | Configurable |
| RooCode | - | No native MCP formatter; `.roo/mcp.json`, `.roo/rules/`, `.roo/skills/` ignores | Configurable |
| Zed | - | No native MCP formatter; `.zed/settings.json` ignore | Configurable |
| Trae AI | - | No native MCP formatter; `.trae/rules/` ignore | Configurable |
| VS Code | - | `.vscode/mcp.json` (native MCP) | Configurable |
| Warp | `WARP.md` | No native MCP formatter | Configurable |
| Kiro | - | No native MCP formatter; `.kiro/steering/`, `.kiro/settings/mcp.json` ignores | Configurable |
| Firebender | - | No native MCP formatter; `firebender.json` ignore | Configurable |
| Factory Droid | - | No native MCP formatter; `.factory/mcp.json`, `.factory/skills/` ignores | Configurable |
| Mistral Vibe | - | No native MCP formatter; `.vibe/config.toml`, `.vibe/skills/` ignores | Configurable |
| JetBrains AI Assistant | - | No native MCP formatter; `.aiassistant/rules/` ignore | Configurable |
| Windsurf | `.windsurfrules` | No native MCP formatter; `.windsurf/mcp_config.json` ignore | Configurable |
| Zed | - | No native MCP formatter; `.zed/settings.json` ignore | Configurable |

**Note (Cursor rules filename):** `.cursor/rules/agentsync.mdc` is the documented example path used by AgentSync for Cursor rules. You may use a different `.mdc` filename/path if you configure it explicitly under your `[agents.<name>.targets.*]` entries.

### What "configurable" means in practice

Expand Down
Loading