{
  "id": "page:docs-plugins-cli-reference",
  "_kind": "Page",
  "_file": "wiki/docs/plugins/cli-reference.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/plugins/cli-reference.md",
    "sourceKind": "repo-docs",
    "title": "Plugin CLI Reference",
    "displayName": "Plugin CLI Reference",
    "slug": "docs/plugins/cli-reference",
    "articlePath": "wiki/docs/plugins/cli-reference.md",
    "article": "\n# Plugin CLI Reference\n\nComplete reference for all `babysitter plugin:*` commands. Every command supports the `--json` flag for machine-readable output and `--verbose` for additional diagnostic information.\n\n## Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Output structured JSON instead of human-readable text |\n| `--verbose` | Enable verbose diagnostic output |\n| `--runs-dir <path>` | Override the default runs directory |\n\n## Scope\n\nMost plugin commands require a scope flag indicating where configuration is stored:\n\n- `--global` — User-wide configuration stored in `~/.a5c/`\n- `--project` — Project-specific configuration stored in `<projectDir>/.a5c/`\n\nWhen `--project` is used, the current working directory is treated as the project root.\n\n---\n\n## plugin:add-marketplace\n\nClones a marketplace repository into the local marketplaces directory.\n\n### Usage\n\n```\nbabysitter plugin:add-marketplace --marketplace-url <url> --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `--marketplace-url <url>` | Git remote URL of the marketplace repository to clone |\n| `--global` or `--project` | Scope for the marketplace clone |\n\n### Example\n\n```bash\nbabysitter plugin:add-marketplace --marketplace-url https://github.com/a5c-ai/babysitter-marketplace.git --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"success\": true,\n  \"url\": \"https://github.com/a5c-ai/babysitter-marketplace.git\",\n  \"scope\": \"global\",\n  \"directory\": \"/home/user/.a5c/marketplaces/babysitter-marketplace\"\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | `--marketplace-url` or `--scope` not provided |\n| `clone_failed` | Git clone failed (bad URL, network error, directory already exists) |\n\n---\n\n## plugin:update-marketplace\n\nPulls the latest changes for a previously cloned marketplace.\n\n### Usage\n\n```\nbabysitter plugin:update-marketplace --marketplace-name <name> --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `--marketplace-name <name>` | Name of the previously cloned marketplace (directory name) |\n| `--global` or `--project` | Scope where the marketplace was cloned |\n\n### Example\n\n```bash\nbabysitter plugin:update-marketplace --marketplace-name babysitter-marketplace --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"success\": true,\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"global\"\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | `--marketplace-name` or `--scope` not provided |\n| `update_failed` | Marketplace directory not found, or git pull failed |\n\n---\n\n## plugin:list-plugins\n\nLists all plugins available in a marketplace manifest.\n\n### Usage\n\n```\nbabysitter plugin:list-plugins --marketplace-name <name> --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `--marketplace-name <name>` | Name of the marketplace to list plugins from |\n| `--global` or `--project` | Scope where the marketplace is cloned |\n\n### Example\n\n```bash\nbabysitter plugin:list-plugins --marketplace-name babysitter-marketplace --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"global\",\n  \"count\": 2,\n  \"plugins\": [\n    {\n      \"name\": \"babysitter@a5c.ai\",\n      \"description\": \"Core babysitter plugin for AI-assisted development\",\n      \"latestVersion\": \"0.0.176\",\n      \"versions\": [\"0.0.176\", \"0.0.175\", \"0.0.174\"],\n      \"packagePath\": \"plugins/babysitter-unified\",\n      \"tags\": [\"core\", \"development\"],\n      \"author\": \"a5c-ai\"\n    }\n  ]\n}\n```\n\n### Human-Readable Output\n\n```\nPlugins in marketplace \"babysitter-marketplace\" (scope: global):\n\n  NAME               VERSION  DESCRIPTION\n  ────               ───────  ────────────────────────────────────────\n  babysitter@a5c.ai  0.0.176  Core babysitter plugin for AI-assisted development\n\n  1 plugin(s) available.\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | `--marketplace-name` or `--scope` not provided |\n| `list_failed` | Marketplace directory not found, or manifest unreadable |\n\n---\n\n## plugin:install\n\nInstalls a plugin from a marketplace. Updates the marketplace first, resolves the plugin version, reads install instructions from the plugin package, and returns them for the agent to execute.\n\n### Usage\n\n```\nbabysitter plugin:install <plugin-name> [--marketplace-name <name>] --global|--project [--plugin-version <ver>] [--json] [--verbose]\n```\n\nThe plugin name can be provided as a positional argument or via `--plugin-name`.\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `<plugin-name>` or `--plugin-name <name>` | Name of the plugin to install |\n| `--global` or `--project` | Scope for the installation |\n\n### Optional Flags\n\n| Flag | Description |\n|------|-------------|\n| `--plugin-version <ver>` | Specific version to install. If omitted, the latest version from the marketplace manifest is used. |\n| `--marketplace-name <name>` | Marketplace containing the plugin. If omitted, the CLI tries to auto-resolve a single configured marketplace for the selected scope. |\n\n### Example\n\n```bash\nbabysitter plugin:install babysitter@a5c.ai --marketplace-name babysitter-marketplace --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"plugin\": \"babysitter@a5c.ai\",\n  \"version\": \"0.0.176\",\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"global\",\n  \"instructions\": \"# Install babysitter@a5c.ai\\n\\n1. Copy the plugin configuration...\\n\",\n  \"processFile\": \"/home/user/.a5c/marketplaces/babysitter-marketplace/plugins/babysitter-unified/install-process.js\"\n}\n```\n\nThe `instructions` field contains the markdown content from `install.md` in the plugin package. The `processFile` field is non-null when an `install-process.js` babysitter process file exists in the plugin package directory.\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | Required flag not provided |\n| `install_failed` | Plugin not found in marketplace, marketplace update failed, or package directory not found |\n\n---\n\n## plugin:uninstall\n\nReads uninstall instructions for a previously installed plugin. Looks up the plugin in the registry to find its marketplace and version, then reads the uninstall instructions from the plugin package.\n\n### Usage\n\n```\nbabysitter plugin:uninstall <plugin-name> --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `<plugin-name>` or `--plugin-name <name>` | Name of the plugin to uninstall |\n| `--global` or `--project` | Scope where the plugin is installed |\n\n### Example\n\n```bash\nbabysitter plugin:uninstall babysitter@a5c.ai --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"plugin\": \"babysitter@a5c.ai\",\n  \"version\": \"0.0.176\",\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"global\",\n  \"instructions\": \"# Uninstall babysitter@a5c.ai\\n\\n1. Remove the plugin configuration...\\n\",\n  \"processFile\": null\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | Required flag not provided |\n| `uninstall_failed` | Plugin not found in registry, or plugin package directory not found |\n\n---\n\n## plugin:update\n\nUpdates an installed plugin to a newer version. Resolves the migration chain from the currently installed version to the target version using BFS shortest-path on available migration files, and returns all migration instructions in order.\n\n### Usage\n\n```\nbabysitter plugin:update <plugin-name> [--marketplace-name <name>] --global|--project [--plugin-version <ver>] [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `<plugin-name>` or `--plugin-name <name>` | Name of the plugin to update |\n| `--global` or `--project` | Scope where the plugin is installed |\n\n### Optional Flags\n\n| Flag | Description |\n|------|-------------|\n| `--plugin-version <ver>` | Specific target version. If omitted, the latest version from the marketplace manifest is used. |\n| `--marketplace-name <name>` | Marketplace containing the plugin. If omitted, the CLI tries to auto-resolve a single configured marketplace for the selected scope. |\n\n### Example\n\n```bash\nbabysitter plugin:update babysitter@a5c.ai --marketplace-name babysitter-marketplace --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"plugin\": \"babysitter@a5c.ai\",\n  \"fromVersion\": \"0.0.174\",\n  \"toVersion\": \"0.0.176\",\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"global\",\n  \"migrations\": [\n    {\n      \"from\": \"0.0.174\",\n      \"to\": \"0.0.175\",\n      \"file\": \"0.0.174_to_0.0.175.md\",\n      \"type\": \"md\",\n      \"instructions\": \"# Migration 0.0.174 to 0.0.175\\n\\n1. Update configuration...\\n\",\n      \"processFile\": null\n    },\n    {\n      \"from\": \"0.0.175\",\n      \"to\": \"0.0.176\",\n      \"file\": \"0.0.175_to_0.0.176.js\",\n      \"type\": \"js\",\n      \"instructions\": \"// Migration process code...\",\n      \"processFile\": \"/path/to/migrations/0.0.175_to_0.0.176.js\"\n    }\n  ]\n}\n```\n\nWhen the installed version already matches the target version, migrations is an empty array with a `message` field:\n\n```json\n{\n  \"plugin\": \"babysitter@a5c.ai\",\n  \"fromVersion\": \"0.0.176\",\n  \"toVersion\": \"0.0.176\",\n  \"migrations\": [],\n  \"message\": \"Already at target version\"\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | Required flag not provided |\n| `update_failed` | Plugin not installed, not found in marketplace, no migration path exists, or marketplace update failed |\n\n---\n\n## plugin:configure\n\nReads configuration instructions for an installed plugin from its plugin package.\n\n### Usage\n\n```\nbabysitter plugin:configure <plugin-name> [--marketplace-name <name>] --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `<plugin-name>` or `--plugin-name <name>` | Name of the plugin to configure |\n| `--global` or `--project` | Scope for the configuration |\n\n### Example\n\n```bash\nbabysitter plugin:configure babysitter@a5c.ai --project --json\n```\n\n### JSON Output\n\n```json\n{\n  \"plugin\": \"babysitter@a5c.ai\",\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"project\",\n  \"instructions\": \"# Configure babysitter@a5c.ai\\n\\n1. Set the API key...\\n\",\n  \"processFile\": \"/path/to/configure-process.js\"\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | Required flag not provided |\n| `configure_failed` | Plugin package directory not found |\n\n---\n\n## plugin:list-installed\n\nLists all plugins recorded in the plugin registry for the given scope.\n\n### Usage\n\n```\nbabysitter plugin:list-installed --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `--global` or `--project` | Scope to list installed plugins for |\n\n### Example\n\n```bash\nbabysitter plugin:list-installed --global --json\n```\n\n### JSON Output\n\n```json\n[\n  {\n    \"name\": \"babysitter@a5c.ai\",\n    \"version\": \"0.0.176\",\n    \"marketplace\": \"babysitter-marketplace\",\n    \"installedAt\": \"2026-03-01T10:30:00.000Z\",\n    \"updatedAt\": \"2026-03-05T14:20:00.000Z\"\n  }\n]\n```\n\n### Human-Readable Output\n\n```\nInstalled plugins (scope: global):\n\n  NAME               VERSION  MARKETPLACE              INSTALLED\n  ────               ───────  ───────────              ────────────────────\n  babysitter@a5c.ai  0.0.176  babysitter-marketplace   2026-03-01T10:30:00.000Z\n\n  1 plugin(s) installed.\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | `--scope` not provided |\n| `list_failed` | Registry file unreadable |\n\n---\n\n## plugin:update-registry\n\nCreates or updates a plugin entry in the registry. Used after the agent has completed the install or update steps to record the installed version.\n\n### Usage\n\n```\nbabysitter plugin:update-registry <plugin-name> --plugin-version <ver> --marketplace-name <name> --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `<plugin-name>` or `--plugin-name <name>` | Name of the plugin |\n| `--plugin-version <ver>` | Version to record |\n| `--marketplace-name <name>` | Marketplace the plugin was sourced from |\n| `--global` or `--project` | Scope for the registry entry |\n\n### Example\n\n```bash\nbabysitter plugin:update-registry babysitter@a5c.ai --plugin-version 0.0.176 --marketplace-name babysitter-marketplace --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"name\": \"babysitter@a5c.ai\",\n  \"version\": \"0.0.176\",\n  \"marketplace\": \"babysitter-marketplace\",\n  \"scope\": \"global\",\n  \"installedAt\": \"2026-03-01T10:30:00.000Z\",\n  \"updatedAt\": \"2026-03-06T09:00:00.000Z\",\n  \"packagePath\": \"/home/user/.a5c/marketplaces/babysitter-marketplace/plugins/babysitter-unified\",\n  \"metadata\": {}\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | Any required flag not provided |\n| `update_registry_failed` | Plugin package path resolution failed, or registry write failed |\n\n---\n\n## plugin:remove-from-registry\n\nRemoves a plugin entry from the registry. Used after the agent has completed the uninstall steps.\n\n### Usage\n\n```\nbabysitter plugin:remove-from-registry <plugin-name> --global|--project [--json] [--verbose]\n```\n\n### Required Flags\n\n| Flag | Description |\n|------|-------------|\n| `<plugin-name>` or `--plugin-name <name>` | Name of the plugin to remove |\n| `--global` or `--project` | Scope for the registry |\n\n### Example\n\n```bash\nbabysitter plugin:remove-from-registry babysitter@a5c.ai --global --json\n```\n\n### JSON Output\n\n```json\n{\n  \"removed\": true,\n  \"plugin\": \"babysitter@a5c.ai\"\n}\n```\n\n### Error Cases\n\n| Error | Cause |\n|-------|-------|\n| `missing_argument` | Required flag not provided |\n| `remove_failed` | Registry read/write failed |\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}