Skip to content

Commands

Jump to bottom
simplifiedmachine edited this page Nov 2, 2026 · 2 revisions

Commands

system-diff [--repo PATH] [--config FILE] COMMAND … (also sysdiff, or python -m system_diff).

  • --repo: the repository (default: the one holding the current directory).
  • --config: a TOML or JSON config, instead of system-diff.toml or pyproject.toml's [tool.system-diff].

map

system-diff map [--ref REF | --dir DIR] [--out DIR] [--check]

The system at a commit (--ref, default HEAD), read from git's object store, or in a folder (--dir . is the working tree). Writes system.json and system.svg into --out (default .). --check writes nothing and exits 1 when the files there are out of date; that is the CI check.

diff

system-diff diff --base A [--head B | --head .] [--out DIR] [--narrate]

What changes from A to B (default HEAD); --head . is the working tree, uncommitted changes included. Both sides are read with the head's config, so a part keeps one name. Writes diff.json, plan.txt, headline.txt, diff.svg (only when something structural changed) and narrative.md.

--narrate asks an LLM for a plain-words summary. It sends the headline, the exact plan and the commit messages, never the code. It uses the first of:

  1. the gateway your Claude Code uses: the env blocks of ~/.claude/settings.json, ~/.claude/settings.local.json, .claude/settings.json and .claude/settings.local.json, then any files [narrate] settings adds, with ANTHROPIC_* in the environment over all of them;
  2. an OpenAI-compatible gateway you exported: SYSTEM_DIFF_LLM_BASE_URL, SYSTEM_DIFF_LLM_API_KEY and SYSTEM_DIFF_LLM_MODEL (or LLM_*).

When nothing answers there is no summary, and nothing else depends on it.

readme

system-diff readme [--json system.json] [--readme FILE] [--stale A,B] [--check]

Rewrites the section between the README's markers: the picture, how it is made, and the outside systems that are read but not drawn (from --json). --stale names pictures that could not be redrawn this time, so the README says they are older than the code. --check exits 1 when the section is out of date.

draw

system-diff draw SPEC.json …

Draws hand-made pictures, each SPEC.svg beside its spec. See Pictures.

png

system-diff png [--host HOST] FILE.svg …

Writes FILE.png beside each SVG, at twice the size, for places that do not show SVG. It uses headless Chromium: Docker here first, then Playwright (pip install "system-diff[png]", then playwright install chromium), else Docker on --host over SSH.

summarize

system-diff summarize --diff diff.json

The --narrate summary alone, for a diff already made.

system-diff

Clone this wiki locally