okfctl

okfctl is a command-line tool built by Casey West for authoring and maintaining Open Knowledge Format (OKF) bundles—structured trees of Markdown "nodes" with a link graph, reserved index.md/log.md files, and frontmatter provenance. It is distributed as a single static Go binary (CGO_ENABLED=0) with no Python environment, model runtime, or external dependencies required. The project is licensed under Apache-2.0 and currently at v0.4.0.

What It Is

okfctl is a spec-conformant CLI that enforces the Open Knowledge Format specification, maintained by Google in the GoogleCloudPlatform/knowledge-catalog repository. The tool's job is to keep Markdown knowledge bases structurally honest: it scaffolds bundles, moves nodes without breaking links, regenerates reserved index files, validates conformance against the OKF spec floor, and reports curation health findings. It does not author the OKF spec—where the spec defines behavior, the spec wins.

Core Workflow

The tool organizes its commands into four functional groups:

• Author: bundle init/info, node new/show/list/edit/mv/rm/refresh/promote, index build/check, log append/show
• Check: validate (spec floor, fails on violation), lint (curation health, advisory by default, CI-gateable with --strict), eval (TACA transparency gate plus accuracy/alignment/calibration sampler)
• Explore: analyze (freshness, clusters, gaps, connectivity), search (lexical and graph-neighborhood, stdlib-only), graph (export as JSON or DOT), serve (interactive web visualization)
• Extend: template, migrate (v0.1 → v0.2), registry, connect, plugin, config, completion, version

A key design point: node mv treats path as identity. Moving a node rewrites every inbound link in the corpus, recomputing relative depth per file, and records the change in log.md. node rm reports orphans it would create rather than silently leaving dangling references.

Architecture and Deployment Model

okfctl is a pure Go, CGO_ENABLED=0 static binary. It ships prebuilt for darwin and linux on amd64 and arm64, and is also available via Homebrew (brew install cwest/tap/okfctl), a one-liner install script, go install, and Debian/RPM packages. Cosign signature verification is supported. There is no model server, no interpreter, and no network dependency at runtime—making it suitable for CI pipelines without additional setup.

Semantic search ships as a separate bundled plugin (okfctl-search --semantic) that uses model2vec, keeping the core binary free of model dependencies.

Agent Plugin Integration

The repository is packaged as an Agent Plugins 1.0.0 package. The root plugin.json bundles four generic okfctl skills—okf-authoring, okf-curation-health, okf-migrate-plan, and okf-semantic-search—as an installable unit for compatible agent clients including Copilot, Cursor, and Codex. Clients that read repo instructions directly pick up the same guidance from AGENTS.md. This is distinct from the okfctl plugin command, which manages executable plugins on PATH.

Update: v0.4.0

The latest release is v0.4.0, published on 2026-08-19. The repository was created in July 2026 and has seen active development, with the last push recorded on 2026-08-21. The project tracks 15 top-level commands, a command-reference drift gate to keep docs in sync with the binary, and a two-phase migration path from OKF v0.1 to v0.2. The eval command introduces a TACA (Transparency, Accuracy, Calibration, Alignment) framework where transparency is the one dimension a no-model tool can gate deterministically; accuracy, calibration, and alignment are scaffolded for a human or out-of-band judge.