Skip to main content

kapi diff

Show the blocks that changed locally relative to the tree the project last declared to the server: like git diff --stat, for content. For each file it reports how many blocks were added, changed, or removed locally, and (when a server is configured) the number of remote changes available to pull.

Without a server, kapi diff still works: it compares against the local sync cache, so it stays useful offline.

Usage​

kapi diff [paths...] [flags]

Examples​

# Summarize all local changes since the last push or pull
kapi diff

# Limit to a directory
kapi diff src/locales/

# List the changed block ids/keys with a source preview
kapi diff --verbose

Example output:

  src/locales/fr/messages.json   +1 ~2 -1

1 file(s) changed: +1 ~2 -1
Remote: 3 change(s) available to pull

Use --verbose to see changed block ids/keys.

With --verbose, each changed block is listed under its file with a change sigil (+ added, ~ changed, - removed) and a source preview.

Options​

FlagDescription
--verboseList changed block ids/keys with a source preview

Output format and color come from the shared global flags:

FlagDescription
--jsonEmit machine-readable JSON instead of text
--output-format <json|text>Select the output format
--jq <expr>Filter JSON output through a jq expression
--color <auto|always|never>Colorize JSON output

How it works​

  1. Resolve the project by walking up from the current directory to the kapi.yaml recipe (run kapi init first if none is found).
  2. Read local files via the format registry, respecting the recipe's collections:.
  3. Compare block-level content against the tree recorded in the local sync cache to compute added, changed, and removed blocks. The tree and the cache are described on kapi push.
  4. When a server is configured, query it for the count of pending remote changes.

Block identity is derived from the block's id/key and source content, so only genuinely changed blocks are reported.

Exit codes​

  • 0: the diff was produced (whether or not changes were found).
  • 1: an error occurred (no project, server unavailable, and so on).