Skip to content

binoc CLI

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

  • binoc diff A B diffs two snapshots and prints a changelog.
  • binoc changelog changesets/*.json combines one or more saved changesets.
  • binoc extract changeset.json PATH ASPECT reopens both snapshots through the comparator chain 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 between two 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 two snapshots and produce a changelog
  • changelog — Generate a human-readable changelog from one or more saved changesets
  • extract — Extract actual changed data from a changeset node

binoc diff

Diff two snapshots and produce a changelog.

Runs the comparator chain over snapshot_a and snapshot_b and emits the resulting changeset. Defaults to human-readable Markdown on stdout; use --format json or -o for machine-readable or multi-output rendering.

Usage: binoc diff [OPTIONS] <SNAPSHOT_A> <SNAPSHOT_B>

Arguments:
  • <SNAPSHOT_A> — Path to the "before" snapshot (file, directory, or archive, depending on which comparators are registered)
  • <SNAPSHOT_B> — Path to the "after" snapshot
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

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 comparator chain and returns the real bytes or text for a given node and 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 comparator that produced the 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