Skip to content

binoc CLI

Binoc ships a single entry point — the binoc console script — with three subcommands:

  • binoc diff A B [C ...] diffs an ordered snapshot sequence and prints pairwise changelog sections.
  • binoc changelog changesets/*.json combines one or more saved changesets.
  • binoc extract changeset.json PATH ASPECT reopens both snapshots through the correspondence engine and prints the actual changed data for a given node.

The three subcommands share the same output-routing flags — -o/--output (repeatable, format:path or bare path), --format (stdout renderer), and -q/--quiet. See the Output routing and CLI UX ADR for the rationale and rejected alternatives. The default stdout renderer is Markdown because the common case is a human at a terminal; machine consumers opt in to JSON via --format json or -o changeset.json.

The reference below is generated from the clap Command tree in binoc-cli/ by just docs-cli. It is the canonical, exhaustive surface. binoc --help and binoc <subcommand> --help print the same information at the terminal.

Command Overview:

binoc

Binoc produces the missing changelog for datasets. It detects, classifies, and renders changes across ordered dataset snapshots. The CLI is porcelain over the embeddable library; see the Python API and Rust SDK reference pages for programmatic use.

Usage: binoc <COMMAND>

Subcommands:
  • diff — Diff an ordered sequence of snapshots and produce a changelog
  • replay — Render a saved run trace as a self-contained HTML replay
  • changelog — Generate a human-readable changelog from one or more saved changesets
  • extract — Extract actual changed data from a changeset node

binoc diff

Diff an ordered sequence of snapshots and produce a changelog.

Runs pairwise comparisons over each consecutive snapshot pair and emits the resulting changeset sequence. Defaults to human-readable Markdown on stdout; use --format json or -o for machine-readable or multi-output rendering.

Usage: binoc diff [OPTIONS] <SNAPSHOTS> <SNAPSHOTS>...

Arguments:
  • <SNAPSHOTS> — Ordered snapshot paths. For N inputs, binoc emits N-1 pairwise diffs (A→B, B→C, ...). Must provide at least two snapshots
Options:
  • --config <CONFIG> — Path to a dataset config YAML file. If omitted, the registry's default config is used
  • -o, --output <OUTPUT> — Write an additional rendered output to a file. Repeatable. Accepts format:path (e.g. markdown:out.md) or a bare path whose format is inferred from the extension
  • --format <FORMAT> — Renderer used for stdout. Accepts json, markdown, or any registered renderer name (the binoc. prefix is optional)

Default value: markdown * -q, --quiet — Suppress stdout. Useful when every rendered output is directed to a file via -o * --trace <TRACE> — Write a detailed replay trace (JSON) of the correspondence run to this path: every expand/parse/link/write/compaction step plus the final side trees and links. Requires exactly two snapshots. Convert it to an interactive HTML replay with binoc replay

binoc replay

Render a saved run trace as a self-contained HTML replay.

Reads a trace JSON produced by binoc diff --trace and writes a single standalone HTML file that animates the comparison: the two snapshot trees growing from the bottom up, links forming between them, and the per-link edit lists building and compacting, with play/step/scrub controls and a detail inspector.

Usage: binoc replay [OPTIONS] <TRACE>

Arguments:
  • <TRACE> — Path to a trace JSON file produced by binoc diff --trace
Options:
  • -o, --output <OUTPUT> — Output HTML path. Defaults to the trace path with a .html extension

binoc changelog

Generate a human-readable changelog from one or more saved changesets.

Reads each changeset JSON file and renders the combined result. Supports the same -o / --format / -q flags as binoc diff.

Usage: binoc changelog [OPTIONS] [CHANGESETS]...

Arguments:
  • <CHANGESETS> — One or more changeset JSON files, typically produced by earlier runs of binoc diff -o changeset.json
Options:
  • --config <CONFIG> — Path to a dataset config YAML file. If omitted, the registry's default config is used
  • -o, --output <OUTPUT> — Write an additional rendered output to a file. Repeatable. Accepts format:path or a bare path whose format is inferred from the extension
  • --format <FORMAT> — Renderer used for stdout. Accepts json, markdown, or any registered renderer name (the binoc. prefix is optional)

Default value: markdown * -q, --quiet — Suppress stdout

binoc extract

Extract actual changed data from a changeset node.

Reopens both snapshots through the correspondence engine and asks the rule that owns the projected node for the requested aspect (e.g. rows_added, diff, content). Use this to recover data that changesets only summarize.

Usage: binoc extract [OPTIONS] <CHANGESET> <NODE> [ASPECT]

Arguments:
  • <CHANGESET> — Path to a changeset JSON file
  • <NODE> — Node path within the changeset (e.g. /path/to/file.csv)
  • <ASPECT> — Named aspect of the node to extract. Which aspects are available depends on the rule that owns the projected node

Default value: content

Options:
  • --snapshot-a <SNAPSHOT_A> — Override the "before" snapshot path. Defaults to the one recorded in the changeset
  • --snapshot-b <SNAPSHOT_B> — Override the "after" snapshot path. Defaults to the one recorded in the changeset
  • --config <CONFIG> — Path to a dataset config YAML file. If omitted, the registry's default config is used