primitree diff

primitree diff <before.tokens.json> <after.tokens.json> --config <path>
                [--source <name>] [--format text|json]
primitree diff <before.json> <after.json> [options]

Configured DTCG comparison

The configured form reads the layer and owner rules from one exact config file. It reports added, removed, and changed tokens. Each change lists the tokens affected through references.

The report also lists new and resolved policy findings. It exits with code 1 when the after file has active findings and code 2 for command, config, or input errors.

primitree diff backup.tokens.json tokens.json \
  --config primitree.config.ts \
  --source brand

Use --format json for one JSON report.

Figma ID comparison

String diffs show a rename as a removal and an addition.

The diff matches variables by stable Figma IDs. The report separates renames, moves, type changes, per-mode values, and description changes.

Usage

primitree diff backup/variables.json variables.json
primitree diff old.json new.json --out CHANGELOG.md
primitree diff old.json new.json --json --out diff.json
primitree diff old.json new.json --fail-on-breaking

Markdown is the default output format. Use --json to write the VariablesDiff object.

Options

Option	Description
`--config <path>`	Read DTCG rules from this config file
`--source <name>`	Select one configured DTCG source
`--format <value>`	Set the configured report format to text or JSON
`--json`	Output the raw diff as JSON instead of Markdown
`--out <file>`	Write output to a file instead of standard output
`--fail-on-breaking`	Exit with code 2 after a breaking change

Example output

Variables: 1 renamed, 1 value change.
**The diff contains breaking changes.**

### Renamed variables (breaking)

- `color/bg/brand` -> `color/bg/primary` (Semantic)

| Variable         | Collection | Mode    | Before | After |
| ---------------- | ---------- | ------- | ------ | ----- |
| `control/height` | Density    | Compact | 32     | 28    |

CI integration

- run: primitree diff backup/variables.json variables.json --fail-on-breaking

See Semantic diffing for the matching rules.