Six subcommands over a bundle or a file, a self-contained Native AOT binary with no runtime to install. validate exits non-zero on a non-conformant bundle, so the whole tool drops into CI as one line.
| Command | Argument | Does |
|---|---|---|
| validate | <bundle> | Check a bundle against OKF v0.1 conformance (§9) |
| info | <bundle> | Summarize concepts, types, links and version |
| index | <bundle> | (Re)generate every index.md (§6) |
| graph | <bundle> | Print the cross-link graph; --dot for Graphviz |
| parse | <file> | Parse one document and print its structure |
| fmt | <file> | Normalize by parse + re-serialize (-w writes) |
Global options: -h/--help prints usage; -V/--version prints the build and spec version. A path beginning with - can be passed after a -- separator.
$ okf --version okf 0.1.0-alpha.1 (OKF spec v0.1)
Loads the bundle, runs the §9 conformance check, and prints every diagnostic followed by a tally. Exits 0 when conformant, 1 otherwise. Warnings never break conformance — only errors do — so recommended-but-missing fields are surfaced without failing the build.
$ okf validate tests/fixtures/appendix_a [warning] tests/fixtures/appendix_a/tables/users.md: missing recommended frontmatter field `description` [warning] tests/fixtures/appendix_a/tables/users.md: missing recommended frontmatter field `timestamp` 4 concept(s); 0 error(s), 2 warning(s), 0 info. ✓ conformant with OKF v0.1
Reports the bundle root, declared OKF version (if any), concept count, reserved-file counts, a breakdown by type, and the internal link total with broken-link count. Unparseable files are listed at the end. Always exits 0.
$ okf info tests/fixtures/appendix_a
bundle: tests/fixtures/appendix_a
concepts: 4
index.md: 0
log.md: 1
types:
1 BigQuery Dataset
3 BigQuery Table
links: 5 internal (0 broken)Regenerates every index.md directory listing in the bundle and prints each path written, then a total. On an empty bundle it prints no index files written (empty bundle?). Exits 0. This command writes files — run it after adding or renaming concepts.
$ okf index ./my_bundle wrote my_bundle/index.md wrote my_bundle/tables/index.md 2 index file(s) regenerated.
Prints each concept's outgoing links. Resolved links use ->, broken ones -x. Pass --dot to emit Graphviz DOT (broken edges dashed and red) — pipe it straight into dot.
$ okf graph tests/fixtures/appendix_a datasets/sales -> tables/orders -> tables/customers tables/customers -> tables/orders tables/orders -> datasets/sales -> tables/customers
$ okf graph tests/fixtures/appendix_a --dot
digraph okf {
rankdir=LR; node [shape=box, fontsize=10];
"datasets/sales" -> "tables/orders";
"datasets/sales" -> "tables/customers";
"tables/customers" -> "tables/orders";
"tables/orders" -> "datasets/sales";
"tables/orders" -> "tables/customers";
}
$ okf graph ./my_bundle --dot | dot -Tsvg > graph.svgParses a single concept document (strict UTF-8) and prints its frontmatter keys, whether it has a non-empty type, the body size in bytes, and any links and citations. Exits 0 if the document is conformant, 1 if not.
$ okf parse tests/fixtures/appendix_a/tables/orders.md frontmatter (6 key(s)): type: BigQuery Table title: Orders description: One row per completed customer order. resource: https://console.cloud.google.com/bigquery?… tags: [sales, orders] timestamp: 2026-05-28T00:00:00Z has non-empty `type`: true body: 99 byte(s) links (2): [Absolute] sales dataset -> /datasets/sales.md [Absolute] customers -> /tables/customers.md
Parses the document and re-serializes it — normalizing frontmatter and block structure while preserving unknown keys byte for byte. Prints to stdout by default; -w (or --write) writes back in place. Exits 0.
$ okf fmt tests/fixtures/appendix_a/tables/orders.md --- type: BigQuery Table title: Orders description: One row per completed customer order. resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders tags: - sales - orders timestamp: 2026-05-28T00:00:00Z --- # Schema Part of the [sales dataset](/datasets/sales.md). FK to [customers](/tables/customers.md).
| Code | Meaning |
|---|---|
| 0 | Success — or, for validate/parse, conformant |
| 1 | Non-conformant, missing argument, unknown subcommand, or I/O error |
Because the binary is self-contained, a CI image needs no .NET runtime, no SDK, no restore:
# any pipeline — fail the build on non-conformant knowledge
okf validate ./bundles/ga4→ library.md — the same engine, as a C# API · getting-started.md
$ git clone https://github.com/jchable/okf4net
$ dotnet publish src/OKF4net.Cli -c Release # self-contained okf binary