The okf CLI

One executable, three kinds of verbs

okf groups its verbs by the kind of question they answer.

Judge verbs assess a bundle. okf validate is the hard gate: is this a legal OKF bundle under section 9 of the spec? okf lint is the advisory report: is it well curated, navigable, trustworthy? okf loose is a focused lens over one lint check: which files float in the graph with no cross-links at all? The conformance model explains why validation and curation stay separate.

Read verbs answer questions about what a bundle contains, without a browser. okf search is ranked text retrieval across metadata and bodies: which concept covers X, answered in a few rows, by a literal scan out of the box or an opt-in BM25+ index (--engine index, and --fuzzy for typo tolerance). okf dirs is the first-glance shape: one row per directory, however big the bundle. okf index is the orientation map, and the only view that shows index.md files. okf catalog, okf files, okf tags, and okf types enumerate concepts by metadata, folder, tag, and type. okf stats sizes the bundle in one screen. okf graph dumps the raw node and edge structure.

Serve and setup verbs stand things up. okf registry keeps a persistent, per-user list of bundles, so any verb can name one as @slug from anywhere. okf server boots the interactive graph in your browser, over one bundle, several, or the whole registry behind one hub. okf render writes that same graph as one static, self-contained HTML file you can host anywhere, no server needed. okf skill installs the companion agent skill that teaches a coding agent to drive everything above.

Extensions add verbs. An installed okf-* gem can register its own verb through the plugin seam, and okf help lists it under installed extensions. The first one shipped is okf mcp from the okf-mcp gem: it serves your registered bundles over the Model Context Protocol, so any MCP-capable host reads them without a shell.

Invocation conventions

Every verb takes the bundle as its one positional argument: okf <verb> <dir> [flags].

• @slug goes wherever a <dir> goes. A bundle registered with okf registry set is nameable from any directory: okf lint @handbook, okf render @ -o graph.html (a bare @ is the registry default). okf search also takes several @slugs, or @all for every registered bundle at once.

• --json is compact by design. Every emitting verb prints single-line JSON, the token-efficient substrate an agent or a script consumes. --pretty indents it for a human and implies --json; the bytes differ, the JSON is identical, so parse either.

• --fields / --except project the JSON on search, index, catalog, and files: --fields a,b keeps only those properties, --except a,b drops them. They are mutually exclusive, both imply --json, and an unknown name is a usage error that lists the valid ones. Projection happens before emission, so you never pay for a field you dropped.

• Plain text is lighter for scanning. The default views print each key once, not per row, so when you only need to read a bundle rather than extract structure, skip --json entirely.

Exit codes

• 0: success.
• 1: a non-conformant bundle (validate), or a lint --fail-on threshold crossed.
• 2: usage error (missing directory, unknown flag, unknown check or field name).

graph, server, and render are best-effort under section 9: a file with invalid frontmatter is skipped and noted on stderr, never fatal, so one bad file cannot take down the rest. The CI guide shows how to turn the codes into a pipeline gate.

All verbs

Verb	Question it answers	Docs
validate	Is this a legal OKF bundle?	okf validate
lint	Is it well curated?	okf lint
loose	Which files float in the graph?	okf loose
search	Which concept covers X?	okf search
dirs	What shape is the bundle, at a glance?	okf dirs
index	How is the bundle mapped for a reader?	okf index
catalog	What concepts are here, in detail?	okf catalog
files	How is it laid out on disk?	okf files
tags	What themes dominate?	okf tags
types	What kinds of knowledge does it hold?	okf types
stats	How big and what shape is it?	okf stats
graph	What are the raw nodes and edges?	okf graph
registry	Can I name my bundles machine-wide?	okf registry
server	Can I explore it visually?	okf server
render	Can I host it as a static file?	okf render
skill	Can my agent learn to do all this?	okf skill
mcp	Can any MCP host read my bundles?	MCP server, ships with the okf-mcp gem