cli-json.md

CLI JSON Output Contract

ADG exposes stable JSON output for read-only plugin commands so external tools can integrate over the CLI boundary without scraping human-formatted text.

General Contract

• Supported commands in this contract:
  • adg plugins list --json
  • adg plugins status --json
  • adg plugins prune --json
• On success, stdout contains exactly one valid JSON document and no human formatting, ANSI color, notes, or tips.
• On failure, diagnostics are written to stderr and the process exits non-zero. JSON error envelopes are not part of this contract.
• Existing fields documented here are stable. Future releases may add fields; callers should ignore unknown fields.

Exit Codes

Code	Meaning
0	Command succeeded; stdout is complete and parseable.
1	Invalid arguments, missing required input, validation/runtime error, unknown option, or command failure.

adg plugins list --json

Shape:

{
  "pluginsDir": "/absolute/path/to/.agents/plugins",
  "plugins": [
    {
      "name": "apple-skills",
      "version": "1.13.2",
      "source": { "type": "github", "repo": "RbBtSn0w/apple-skills" },
      "sourceHash": "sha256-...",
      "installedHash": "sha256-...",
      "installedAt": "2026-06-26T00:00:00.000Z",
      "updatedAt": "2026-06-26T00:00:00.000Z",
      "path": "/absolute/path/to/.agents/plugins/RbBtSn0w__apple-skills/apple-skills",
      "agents": ["claude", "codex", "antigravity"],
      "contents": {
        "skills": ["xcode-build-fixer"],
        "agents": [],
        "commands": [],
        "mcp": ["xcode"],
        "hooks": [],
        "apps": []
      },
      "counts": {
        "skills": 1,
        "agents": 0,
        "commands": 0,
        "mcp": 1,
        "hooks": 0,
        "apps": 0
      },
      "partial": false,
      "state": "enabled"
    }
  ]
}

Field notes:

• pluginsDir and each path are absolute filesystem paths.
• source is ADG's lock-file provenance object.
• agents contains stable agent ids, not display names. Indicates which agents can adapt this plugin's component types (for active per-agent runtime projection status, see adg plugins status --json).
• contents always includes every component category, using empty arrays when a plugin has none of that category.
• counts mirrors contents lengths.
• partial is true when the installed plugin has a stored partial-install selection.
• state is always normalized to enabled or disabled; legacy lock entries without an explicit state are reported as enabled.

adg plugins status --json

Shape:

{
  "pluginsDir": "/absolute/path/to/.agents/plugins",
  "scope": "user",
  "targets": ["claude"],
  "statuses": [
    {
      "id": "claude",
      "displayName": "Claude Code",
      "queryable": true,
      "inSync": ["apple-skills"],
      "missing": [],
      "agentOnly": [],
      "disabled": [],
      "unexpectedlyEnabled": []
    }
  ]
}

Field notes:

• scope is the agent install scope: user for --global, otherwise project.
• targets contains the resolved target ids requested by --target; omitted --target resolves to all registered targets.
• queryable: false means the agent CLI could not be queried; the arrays are then empty because live state is unknown. When the CLI ran but rejected the query, queryError contains its diagnostic and recoveryCommand contains a safe repair command when ADG recognizes the failure. Both fields are omitted when unavailable.
• inSync and missing apply only to store-enabled plugins. disabled contains store-disabled plugins absent from the runtime as intended; unexpectedlyEnabled contains disabled plugins still active in that runtime. agentOnly remains reserved for runtime plugins absent from the store. Codex detailed queries additionally expose runtimeMissing and runtimeDisabled, splitting the existing missing array without changing it. Other agents may omit these optional fields. Detailed queries also expose runtimePlugins: scoped native records with id, name, installed, enabled, and optional version. A version on an installed record describes the native registration; a version on an available, uninstalled record describes the catalog. Missing or null native versions are omitted rather than guessed. These records do not prove which version an existing session has loaded. An older installed-only response is supported; an omitted available list does not imply additional installed plugins. JSON is parsed from stdout; successful CLI warnings on stderr do not make a valid snapshot unknown. Malformed or contradictory state remains a query error. Content drift is not represented; use adg plugins sync when a full runtime refresh is required.

adg plugins prune --json

Shape:

{
  "targets": ["claude", "codex", "antigravity"],
  "results": [
    {
      "agent": "claude",
      "skipped": false,
      "removed": [
        { "name": "adg-deadbeef", "path": "/var/folders/.../T/adg-cache-sandbox-xyz/state/plugins" }
      ],
      "errors": []
    },
    { "agent": "codex", "skipped": false, "removed": [], "errors": [] },
    { "agent": "antigravity", "skipped": true, "removed": [], "errors": [] }
  ]
}

Field notes:

• targets contains the resolved target ids requested by --target; omitted --target resolves to all registered targets.
• skipped: true means either the agent's CLI wasn't available, or the agent has no persistent external registry to prune (e.g. Antigravity's file-projection model — it has nothing analogous).
• removed lists every ADG-owned registration (adg / adg-<hash>) actually deleted because its path no longer exists on disk. A registration ADG didn't create, or whose directory is still there, is never listed or touched.
• errors carries diagnostics for entries recognized as stale that could not be removed (the agent's CLI rejected the removal, etc) — these are not fatal; other agents/entries are still processed.