Skip to content

Install and use plugins

Goal. Extend binoc with domain-specific format support by installing a plugin package.

Prerequisites. binoc working at the command line (see Diff two snapshots).

The one-liner

Plugins are regular Python packages distributed on PyPI. Install one and it becomes available automatically — no configuration required:

pip install binoc-sqlite
binoc diff snapshots/v1 snapshots/v2

With uvx you can run binoc plus a plugin without installing anything permanently:

uvx --with binoc-sqlite binoc diff snapshots/v1 snapshots/v2

Either way, .sqlite / .db files in the snapshots now get semantic schema and row-count diffs instead of "content changed".

How it works

At startup, binoc scans Python entry points in the group binoc.plugins and loads everything it finds. An installed plugin package declares an entry point in its pyproject.toml and exposes either a register(registry) function (for Python plugins) or a native module (for Rust plugins built with maturin). Either way, the host learns about the plugin's available surfaces at startup.

You don't need to "enable" the plugin to load it; installing the package is enough. Dataset-specific semantics still belong in dataset config when a plugin documents them.

See Plugin discovery for the exact strings involved, and Plugin model for the conceptual overview.

Where do plugins come from?

The binoc-* namespace on PyPI is the shared ecosystem namespace (similar to pytest-* or llm-*). Published reference plugins today include:

  • binoc-sqlite — SQLite schema and row-count diffing.
  • (More plugins will land here as the ecosystem grows.)

For in-tree reference implementations see the model-plugins/ directory in the repository. They double as worked examples for the current Plugin model.

List what's registered

Once a plugin is installed, any stable plugin surfaces it exposes are available through the host. Current diff behavior uses correspondence rule packs and renderer plugins.

For current dataset semantics, use dataset config. For the rule-family dispatch model, see Dispatch model.

Trust

Plugins run in-process with the host's privileges. Only install plugins from sources you trust at least as much as you trust running their code on your machine. See Security and trust for the short version and Security posture and auditing ADR for the long version.

Where to go next