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 query — Query the bundle’s concept graph (lookup|neighbors|neighborhood|pattern|path)
binder graph schema-describe — Introspect the property graph(s) binder can project from a bundle
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/<version>"; 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/<version>))
      --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 (a rerun writes nothing — verified stamps dedup by actor by, so a repeat run with the same verifier never appends duplicate timestamps), 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/<version>"; 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/<version>))

binder graph query

Query the bundle’s concept graph (lookup|neighbors|neighborhood|pattern|path)

Synopsis

Query runs one of five read-only verbs over the property graph binder projects from an OKF bundle — the same graph as binder graph, list_graphs, and project, so it stays in edge/identity parity by construction.

–op lookup list a concept by –id or all of a –label –op neighbors one-hop from –id (–direction out|in|both, optional –rel) –op neighborhood bounded k-hop BFS from –id (–depth 1..5) –op pattern source nodes of –label linking to –to-label and/or a –where-prop/–where-eq predicate (type|tier|stale) –op path bounded shortest hop-path from –from to –to (–max-depth 1..5)

Every traversal is bounded; a query that matches nothing is a result, not an error. Output is the binder.report/v1 query_graph payload. –id-key is accepted for parity with schema-describe but does NOT re-key traversal identity in this version (identity is always the path-derived concept id).

binder graph query <bundle> --op <verb> [flags]

Options

      --depth int           neighborhood: BFS depth, required, 1..5
      --direction string    neighbors/neighborhood/path: out|in|both (default out)
      --from string         path: the source node id (required for path)
  -h, --help                help for query
      --id string           lookup/neighbors/neighborhood: the subject node id (path-derived concept id)
      --id-key string       accepted for parity with schema-describe; does NOT re-key traversal identity in this version
      --label string        lookup: the concept type to list; pattern: the source concept type (required for pattern)
      --max-depth int       path: maximum hop depth, required, 1..5
      --op string           the query verb: lookup|neighbors|neighborhood|pattern|path (required)
      --rel string          neighbors/neighborhood/pattern: optional exact-match filter on the edge relationship text
      --to string           path: the target node id (required for path)
      --to-label string     pattern: optional target concept type
      --today string        date (YYYY-MM-DD) used for staleness; defaults to now
      --where-eq string     pattern: the exact value the property must equal
      --where-prop string   pattern: property predicate target: type|tier|stale

binder graph schema-describe

Introspect the property graph(s) binder can project from a bundle

Synopsis

Schema-describe reports the property graph(s) binder can project from an OKF bundle: graph name, node labels (the concept types present) and the single LINKS edge label, each with property declarations and counts. It is derived from the same projection as binder graph, so it stays in parity by construction.

Read-only; output is the binder.report/v1 list_graphs payload. 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 (spec §2).

binder graph schema-describe <bundle> [flags]

Options

  -h, --help            help for schema-describe
      --id-key string   frontmatter key to prefer as the stable node key; empty falls back to path-as-identity (spec §2)
      --today string    date (YYYY-MM-DD) used for staleness; defaults to now

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.

It also reports unquoted colon-space scalars: any frontmatter key whose unquoted plain-scalar value contains “: “ (e.g. title: Multi-View: Tabs), which YAML tries and rejects as a nested mapping rather than the intended string. A colon-tab counts the same, and a flow mapping is scanned too (one level in when written on a single line). Quoting the value is the fix. This one is advisory-only and never gates, even under –strict: it is derived only for a file whose frontmatter did not parse, and names the key to quote in a file already reported as an invalid-frontmatter schema violation.

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
      --require-tier string   minimum trust tier required for every concept ("machine-confirmed" or "human-reviewed"); gates (exit 1) when any concept is below this tier
      --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 query

Synopsis

Options

SEE ALSO

binder graph schema-describe

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