diff

Preview the pending configuration changes for a single harness.

SynopsisCopy Anchor Link

apothem diff --harness NAME [--profile PATH] [--project PATH]
             [--quiet|-q] [--verbose|-v]
             [--format plain|json] [--json] [--no-color]

diff is a read-only inspection command. It runs the same materialization the install command would run, but in dry-run mode — nothing is written to disk. For each pending target it renders a plain-language action (for example Write file, Merge directory, Install skills, or Prune stale files), the target path, a preview status (would create, would update, would remove, or no change), and — for operator-owned anchors that would be merged — the unified diff of the change. The status is computed by comparing the source against the current on-disk target, so an already-matching target reads no change and is hidden from the default view. It is the answer to "what would apothem install do to this harness right now?" without making the change.

The plan covers every path the install writes: the manifest entries, the harness's own config file (for example opencode.json or config.yaml), the instruction anchor or profile document the shared profile is projected into (such as CLAUDE.md), and the shared data stores under .apothem/. Right after an install, diff reports no pending change; a re-install then writes nothing and takes no new backup. install --dry-run shows the same plan.

For the adapters that write skills to your home directory, the plan lists those folders with their home paths, ahead of the project files, and a skill folder that Apothem did not write appears as a skill_conflict warning.

For operator-owned targets — files that carry both your own content and an Apothem-managed block — the diff shows the exact lines that would change. For other targets, the planned action and preview status are summarized.

The default view lists only pending changes. Pass --verbose to see the full plan, including unchanged targets, annotated with the raw internal operation kind and outcome. The --json envelope is unaffected by the display layer: it always carries the raw operation and outcome fields for machine consumers.

diff operates on a single harness. Unlike install or verify, it does not accept all; pass one harness name.

OptionsCopy Anchor Link

JSON outputCopy Anchor Link

The --json envelope mirrors the dry-run install envelope. status is dry_run, files_written is always empty, and the materialization block plus the results list carry the full planned-target detail. Each operator-owned result row's detail.diff field carries the unified diff string.

{
  "schema_version": 1,
  "status": "dry_run",
  "command": "diff",
  "action": "dry_run",
  "harness": "claude-code",
  "files_written": [],
  "results": [
    {
      "harness": "claude-code",
      "outcome": "updated",
      "operation": "sentinel_merge",
      "path": "C:\\Users\\Example\\.claude\\CLAUDE.md",
      "message": "dry run: no filesystem changes made",
      "detail": {
        "ownership_class": "operator-owned",
        "diff": "--- a/CLAUDE.md\n+++ b/CLAUDE.md\n@@ ..."
      }
    }
  ],
  "warnings": [],
  "error": null,
  "materialization": { "...": "..." }
}

ExamplesCopy Anchor Link

apothem diff --harness claude-code
apothem diff --harness cursor --project .
apothem diff --harness claude-code --json

Exit codesCopy Anchor Link

See alsoCopy Anchor Link

• apothem status — report install/verify/drift across every harness
• apothem verify — verify a harness adapter installation
• apothem install — apply the previewed changes