Command reference

Generated from binder’s Cobra command tree by make docs (cmd/gendocs). Do not edit by hand; a drift test (internal/gendocs) fails CI if these files fall out of sync with the command tree.

binder config get — Get the resolved value of a configuration key
binder config list — List all resolved configuration values and their sources
binder config set — Set a persistent configuration value in .binder.yaml or user config
binder config unset — Remove a persistent configuration value
binder config — Manage configuration (show, get, set, unset)
binder convert — Convert a markdown corpus into an OKF v0.2 bundle
binder enrich — Inject missing OKF frontmatter into a source markdown tree, in place
binder graph — Export the bundle’s concept graph (dot|json|graphml|html)
binder index — (Re)generate the per-directory index.md nav tree (spec §8)
binder infer — Inspect a source markdown corpus and propose a –type-map
binder lint — Check a source markdown corpus for broken links, missing titles, orphans, stale, schema issues
binder mcp — Run binder as a stdio MCP server (additive verbs as MCP tools)
binder project — Project a bundle into offline property-graph DDL (Spanner SQL/PGQ)
binder review — Summarize a bundle: concepts, unresolved links, orphans, trust tiers, stale
binder validate — Check a bundle for OKF v0.2 conformance (spec §11)
binder — Convert a plain-markdown corpus into a conformant OKF v0.2 bundle

binder

Convert a plain-markdown corpus into a conformant OKF v0.2 bundle

binder [flags]

Options

  -h, --help   help for binder

binder config get

Get the resolved value of a configuration key

binder config get <key> [flags]

Options

  -h, --help   help for get
      --json   emit the result as JSON (schema binder.config/v1)

binder config list

List all resolved configuration values and their sources

binder config list [flags]

Options

  -h, --help   help for list
      --json   emit the resolved config as deterministic JSON (schema binder.config/v1)

binder config set

Set a persistent configuration value in .binder.yaml or user config

Synopsis

Set persists a configuration setting to ./.binder.yaml (default) or ~/.config/binder/config.yaml (with –global).

It performs isolated file mutation, modifying only the specified key without altering other settings or dumping runtime defaults.

binder config set <key> <value> [flags]

Options

  -g, --global   write setting to global user config (~/.config/binder/config.yaml) instead of ./.binder.yaml
  -h, --help     help for set
      --json     emit the result as JSON (schema binder.config/v1)

binder config unset

Remove a persistent configuration value

Synopsis

Unset removes a key from ./.binder.yaml (default) or ~/.config/binder/config.yaml (with –global), reverting the setting to its environment override or built-in default.

binder config unset <key> [flags]

Options

  -g, --global   remove setting from global user config (~/.config/binder/config.yaml) instead of ./.binder.yaml
  -h, --help     help for unset
      --json     emit the result as JSON (schema binder.config/v1)

binder config

Manage configuration (show, get, set, unset)

Synopsis

Config manages persistent settings and prints the resolved effective configuration: each key’s value and its source (flag, env, file, or default), plus the config file that was read (if any). Precedence is flag > env > config file > built-in default. Ships –json (schema binder.config/v1).

binder config [flags]

Options

  -h, --help   help for config
      --json   emit the resolved config as deterministic JSON (schema binder.config/v1)

binder convert

Convert a markdown corpus into an OKF v0.2 bundle

Synopsis

Convert walks a plain-markdown corpus and writes a conformant OKF v0.2 bundle: one concept per non-reserved .md, standard markdown links rewritten to bundle-relative form, a root index.md declaring okf_version, and a generated provenance stamp. Output is deterministic for identical inputs, with a single time-varying field: the generated provenance timestamp (generated.at), which records when the run actually happened. Pin SOURCE_DATE_EPOCH to make output byte-identical across runs.

binder convert <src> [flags]

Options

      --canonicalize-status         opt-in: rewrite known --status-map aliases to the OKF §5.4 vocabulary (active->stable, wip/in-progress->draft, archived/legacy->deprecated); off by default, each rewrite is reported
      --default-type string         type applied when none is present or mapped (default "Note")
      --dry-run                     report what would be written without writing anything
      --external-root stringArray   declare a KNOWN sibling-workspace root (repeatable); file:// links under it stay external but suppress the outside-root advisory
      --fm-ref-keys string          frontmatter keys treated as relationship edges, e.g. "related,parent"
      --group-by-type               append an additive "# Catalog" of all concepts grouped by type to the root index.md
  -h, --help                        help for convert
      --include-backlinks           annotate catalog entries with inbound resolved edges (requires --group-by-type)
      --include-graph               annotate catalog entries with outbound resolved edges (requires --group-by-type)
      --json                        emit the run report as deterministic JSON (schema binder.report/v1) instead of prose
      --map-citations               map a body "# Citations" list into sources entries
      --map-draft                   map a draft:true marker to status:draft when status is absent
  -o, --output string               output bundle directory
      --report string               also write the run report to this file
      --source-keys string          frontmatter keys to map into sources entries, e.g. "source,author"
      --stale-after-map string      per-directory stale_after relative to now, e.g. "07-benchmarks=+6m,legacy=+0d" (grammar +Nd/+Nm/+Ny; set only when absent)
      --status-map string           per-directory status, e.g. "archive=deprecated,drafts=draft,default=active" (set only when status absent)
      --strict                      gate (exit 1) on unresolved links or recovery warnings; without it these never gate (never-reject)
      --type-map string             per-directory type overrides, e.g. "docs=Guide,adr=Decision"
      --verified-by string          actor to append as a verified stamp, e.g. "human:ghchinoy" or "binder/0.3.0"; a stamp is written ONLY when passed here, or when verified_by is set in your GLOBAL config (neither BINDER_VERIFIED_BY nor a repo-local .binder.yaml authorizes stamping; valid forms: human:<id>, process:<id>, team:<id>, or <producer>/<version> (e.g. binder/0.3.0))
      --workspace-root string       boundary within which file:// links resolve to internal edges (default: the <src> root)

binder enrich

Inject missing OKF frontmatter into a source markdown tree, in place

Synopsis

Enrich adds the missing required OKF frontmatter (type, title, generated) to the markdown files under , IN PLACE. It touches FRONTMATTER ONLY: unlike binder convert, it does no link rewriting, no index generation, no “## Related” section, and no tag merge — bodies are otherwise untouched.

It operates on the YAML only, so its writes stay reviewable on a git-tracked tree: additive/never-clobber (it adds only ABSENT keys and never overwrites an existing value; the sole exception is an authorized verified stamp, which is APPENDED to any existing verified list, never replacing a prior attestation), idempotent unless a verified stamp advances (a rerun writes nothing when no verifier is set or the clock is pinned via SOURCE_DATE_EPOCH; with a live verifier under a moving clock a rerun appends a fresh stamp, since stamps dedup on (by, at)), and atomic (temp file + rename, so an interrupted run leaves the source as it was rather than half-written). Files needing no key are not written at all. Files whose frontmatter will not parse, and reserved files (index.md/log.md), are skipped and never mutated.

Additive/never-clobber is the DEFAULT. –overwrite-keys <k1,k2,…> is an opt-in exception that REFRESHES only the named keys in place even when they already exist (e.g. –overwrite-keys status,stale_after after a new benchmark release). Every other pre-existing key, custom frontmatter, and key order are left in place; it respects –dry-run, the atomic write, and skip-unchanged. Trust/attestation keys (verified, verified_by, sources, generated, and the other provenance keys) are REFUSED (exit 2) — overwriting them could destroy a human attestation.

Use –dry-run to preview. Skipped files, preserve-or-advise warnings, and a non-conformant –status-map OKF §5.4 value are advisory: bare enrich exits 0; –strict gates (exit 1) on them — the status-map value gates BEFORE anything is written. The read-boundary normalization advisory (a stripped UTF-8 BOM or a translated lone CR) is always reported and never gates.

binder enrich <src> [flags]

Options

      --canonicalize-status      opt-in: rewrite known --status-map aliases to the OKF §5.4 vocabulary (active->stable, wip/in-progress->draft, archived/legacy->deprecated); off by default, each rewrite is reported
      --default-type string      type applied when none is present or mapped (default "Note")
      --dry-run                  report what would be enriched without writing anything
  -h, --help                     help for enrich
      --json                     emit the run report as deterministic JSON (schema binder.report/v1) instead of prose
      --overwrite-keys string    opt-in: comma-separated keys to REFRESH in place even when present, e.g. "status,stale_after" (default is additive/never-clobber; trust keys attester, computation, executor, generated, parameters, runtime, sources, usage_window, verified, verified_by are refused)
      --stale-after-map string   per-directory stale_after relative to now, e.g. "07-benchmarks=+6m,legacy=+0d" (grammar +Nd/+Nm/+Ny; set only when absent)
      --status-map string        per-directory status, e.g. "archive=deprecated,drafts=draft,default=active" (set only when status absent)
      --strict                   gate (exit 1) on any of enrich's gating conditions, including a skipped file, a preserve-or-advise warning, and a non-conformant --status-map OKF §5.4 value; the read-boundary normalization advisory is reported but never gates; without it enrich never gates (never-reject)
      --type-map string          per-directory type overrides, e.g. "docs=Guide,adr=Decision"
      --verified-by string       actor to append as a verified stamp, e.g. "human:ghchinoy" or "binder/0.3.0"; a stamp is written ONLY when passed here, or when verified_by is set in your GLOBAL config (neither BINDER_VERIFIED_BY nor a repo-local .binder.yaml authorizes stamping; valid forms: human:<id>, process:<id>, team:<id>, or <producer>/<version> (e.g. binder/0.3.0))

binder graph

Export the bundle’s concept graph (dot|json|graphml|html)

Synopsis

Graph exports the bundle’s concept graph. Edges are exactly the bundle’s resolved links (spec §6), so the graph matches validate and review. Output is deterministic.

graph is already machine-readable, so –json is an alias for –format json (the raw {nodes,edges} export, NOT the report envelope used by the other commands). Combining –json with a conflicting –format is a usage error.

binder graph <bundle> [flags]

Options

      --format string   output format: dot|json|graphml|html (default "dot")
  -h, --help            help for graph
      --json            alias for --format json (the raw {nodes,edges} export, not the report envelope)
  -o, --output string   write graph to a file instead of stdout
      --today string    date (YYYY-MM-DD) used for staleness; defaults to now

binder index

(Re)generate the per-directory index.md nav tree (spec §8)

Synopsis

Index regenerates each directory’s index.md as a navigation tree listing that directory’s concepts and immediate subdirectories (spec §8). The bundle-root index.md declares okf_version (spec §12). log.md files are never touched. Existing index.md files are regenerated; each write is reported so nothing is overwritten silently.

binder index <bundle> [flags]

Options

      --dry-run             report which index.md files would be written without writing
      --group-by-type       append an additive "# Catalog" of all concepts grouped by type to the root index.md
  -h, --help                help for index
      --include-backlinks   annotate catalog entries with inbound resolved edges (requires --group-by-type)
      --include-graph       annotate catalog entries with outbound resolved edges (requires --group-by-type)

binder infer

Inspect a source markdown corpus and propose a –type-map

Synopsis

Infer inspects a source markdown corpus and proposes a directory-to-type mapping string (e.g. “docs=Guide,subsystems=Subsystem”) and structured report.

It evaluates a tiered signal ladder: deterministic offline signals by default (folder structure, filename patterns, frontmatter hints), plus an optional opt-in Gemini semantic tier (–gemini) supporting API keys and Google Cloud Vertex AI with Application Default Credentials.

Infer is proposal-only: it never writes to disk. Review the proposal, then pass it to binder convert --type-map or binder enrich --type-map.

binder infer <corpus> [flags]

Options

      --backend string        Gemini auth backend: auto, api, or vertex (default "auto")
      --default-type string   fallback concept type (default "Note")
      --gemini                enable Gemini semantic inference tier (requires API key or Google Cloud ADC)
      --gemini-model string   Gemini model for semantic inference (default "gemini-3.5-flash-lite")
      --gemini-required       fail on Gemini inference error instead of degrading to deterministic tiers
  -h, --help                  help for infer
      --json                  emit the inference report as deterministic JSON (schema binder.report/v1)
      --location string       Google Cloud location for Vertex AI (default "global")
      --project string        Google Cloud project for Vertex AI (defaults to ADC / GOOGLE_CLOUD_PROJECT)
      --strict                gate (exit 1) if any warning or failure occurs

binder lint

Check a source markdown corpus for broken links, missing titles, orphans, stale, schema issues

Synopsis

Lint performs a read-only pass over a SOURCE markdown corpus (it writes nothing) and reports broken links (incl. #anchors), missing titles, orphan concepts, entrypoints, stale concepts, and schema violations (missing type:, invalid frontmatter). A concept with no inbound links is an ENTRYPOINT when it links out (or is a recognized root README.md, or is named via –entrypoint) and a true ORPHAN only when it has no inbound AND no outbound links. Unlike binder review/binder validate, which read an emitted bundle, lint sees the corpus as authored — a missing title or type: is masked once convert defaults it.

Findings are advisory: bare lint always exits 0 (entrypoints never gate). Use –strict to gate (exit 1) when any finding is present, e.g. in CI.

binder lint <corpus> [flags]

Options

      --entrypoint strings   concept id or path to treat as an entrypoint, not an orphan (repeatable); root README.md is recognized automatically
  -h, --help                 help for lint
      --json                 emit the lint report as deterministic JSON (schema binder.report/v1) instead of prose
      --strict               gate (exit 1) when any lint finding is present; without it lint never gates (never-reject)
      --today string         date (YYYY-MM-DD) used for staleness; defaults to now

binder mcp

Run binder as a stdio MCP server (additive verbs as MCP tools)

Synopsis

MCP starts a Model Context Protocol server over stdio, exposing binder’s additive verbs as tools to an MCP-capable agent harness (Claude Code, Cursor, Zed). Each tool returns the same deterministic binder.report/v1 payload as the corresponding binder <cmd> --json, reusing the same internal entry points and JSON encoder — no second serialization path.

Tools: convert, validate, review, lint, graph, list_graphs, query_graph.

The server serves over stdio until the client disconnects. Wire it into a harness, e.g.: claude mcp add binder – binder mcp

binder mcp [flags]

Options

  -h, --help   help for mcp

binder project

Project a bundle into offline property-graph DDL (Spanner SQL/PGQ)

Synopsis

Project emits a deterministic, credential-free property-graph schema for a loaded OKF bundle. It writes schema.ddl (CREATE TABLE Nodes, Edges and the NodeVerified attestation table plus a CREATE PROPERTY GRAPH wrapper with a single LINKS edge label) to –out and prints a binder.report/v1 summary to stdout.

The projection reuses the same node/edge model as binder graph, list_graphs, and query_graph, so it stays in edge/identity parity by construction. Node identity (node_key) is the concept’s authored frontmatter value under –id-key when present and non-empty, otherwise the path-derived concept id; binder NEVER mints a key. The tier/stale columns are the frozen projection-time snapshot as of –today (SOURCE_DATE_EPOCH-honoring); stale_after carries the raw authored input so stale stays re-derivable.

Alongside schema.ddl it emits the loader row data (nodes.csv, edges.csv, load.sql) and the provenance artifacts node_verified.csv (the verified[] attestations, copied losslessly: order preserved, by/at verbatim as authored, is_human = the human: prefix) and derivation.sql (a CREATE VIEW that recomputes tier/stale from stale_after and NodeVerified for any date). –target defaults to spanner and is the only accepted value in this release. No cloud credentials are used or needed.

binder project <bundle> --out <dir> [flags]

Options

  -h, --help            help for project
      --id-key string   authored frontmatter key to use as node identity; falls back to path identity per concept
      --out string      output directory for emitted artifacts (required)
      --target string   projection target dialect (only "spanner" in v0.4.0) (default "spanner")
      --today string    date (YYYY-MM-DD) used for the frozen tier/stale snapshot; defaults to now

binder review

Summarize a bundle: concepts, unresolved links, orphans, trust tiers, stale

Synopsis

Review reports the bundle’s concepts by type, derived trust tiers, stale concepts, Attested Computations, entrypoints, orphans, and unresolved links. A concept with no inbound links is an ENTRYPOINT when it links out (or is a recognized root README.md, or is named via –entrypoint) and a true ORPHAN only when it has no inbound AND no outbound links. Trust tiers and staleness are derived on demand, never stored (spec §5.1/§5.3).

binder review <bundle> [flags]

Options

      --entrypoint strings   concept id or path to treat as an entrypoint, not an orphan (repeatable); root README.md is recognized automatically
  -h, --help                 help for review
      --json                 emit the review report as deterministic JSON (schema binder.report/v1) instead of prose
      --strict               gate (exit 1) when any review finding is present (orphans, stale, unresolved, unparsed)
      --today string         date (YYYY-MM-DD) used for staleness; defaults to now

binder validate

Check a bundle for OKF v0.2 conformance (spec §11)

Synopsis

Validate checks the hard conformance rules: every non-reserved .md has a parseable frontmatter block with a non-empty type. It reports trust well-formedness as advisories and NEVER rejects a bundle for missing optional fields, unknown keys, unknown type values, broken links, or absent trust families.

binder validate <bundle> [flags]

Options

  -h, --help     help for validate
      --json     emit the validation result as deterministic JSON (schema binder.report/v1) instead of prose
      --strict   gate (exit 1) on trust well-formedness advisories, not just hard non-conformance

Command reference

binder

Options

SEE ALSO

binder config get

Options

SEE ALSO

binder config list

Options

SEE ALSO

binder config set

Synopsis

Options

SEE ALSO

binder config unset

Synopsis

Options

SEE ALSO

binder config

Synopsis

Options

SEE ALSO

binder convert

Synopsis

Options

SEE ALSO

binder enrich

Synopsis

Options

SEE ALSO

binder graph

Synopsis

Options

SEE ALSO

binder index

Synopsis

Options

SEE ALSO

binder infer

Synopsis

Options

SEE ALSO

binder lint

Synopsis

Options

SEE ALSO

binder mcp

Synopsis

Options

SEE ALSO

binder project

Synopsis

Options

SEE ALSO

binder review

Synopsis

Options

SEE ALSO

binder validate

Synopsis

Options

SEE ALSO