okfctl is a command-line tool for authoring and maintaining Open Knowledge Format (OKF) bundles — a curated tree of Markdown "nodes" with a link graph, reserved index.md/log.md files, and frontmatter provenance.

Website: okfctl.dev • Docs: docs/ • Contributing: CONTRIBUTING.md • Security: SECURITY.md • Conduct: CODE_OF_CONDUCT.md

OKF is a specification okfctl consumes — it does not author it. The Open Knowledge Format spec is the authority; where the spec defines behavior, the spec wins. The tool enforces the spec floor for everyone and keeps anything stricter behind an explicit opt-in overlay (--templates, §9.4), so an unknown type or a future frontmatter key never fails validate.

Use it to scaffold a bundle, add and move nodes without breaking links, keep the reserved index and change log current, check a corpus against the spec, and inspect its health and link graph. It is pure Go with no CGO, no Python, and no model runtime.

Install

The quickest paths, in order of least friction:

Homebrew (macOS, or Linux with Homebrew):

brew install cwest/tap/okfctl

One-liner (macOS and Linux) — detects your OS/arch, downloads the matching release archive, verifies its checksum against the release's checksums.txt, and installs both okfctl and okfctl-search onto your PATH. It refuses to install on a checksum mismatch:

curl -sSL https://okfctl.dev/install.sh | sh

Go toolchain — install from source:

go install github.com/cwest/okfctl@latest

Prebuilt binaries — download for your platform from the releases page: macOS, Linux, and Windows, on amd64 and arm64. Each archive bundles both okfctl and the okfctl-search plugin — extract them onto your PATH:

tar -xzf okfctl_<version>_<os>_<arch>.tar.gz     # or unzip the .zip on Windows
sudo mv okfctl okfctl-search /usr/local/bin/

Linux users can also install a system package:

sudo dpkg -i okfctl_<version>_linux_<arch>.deb    # Debian/Ubuntu
sudo rpm -i  okfctl_<version>_linux_<arch>.rpm    # Fedora/RHEL

Every release ships an SBOM (syft) and is signed with cosign (keyless via Sigstore). Verify the checksums file, which covers every artifact:

cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/cwest/okfctl/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

Verify the install and the reported version:

okfctl version        # e.g. okfctl v0.2.0 (commit <sha>, built <date>)
okfctl --version      # same string

To build from source instead:

go build -o okfctl .                    # dynamic build; version reports "dev"
CGO_ENABLED=0 go build -o okfctl .      # static, no cgo

60-second quickstart

Starting from an empty directory, scaffold a bundle, add a node, build the index, and validate — a full cold start:

okfctl bundle init mykb                                              # scaffold a conformant bundle
okfctl node new concepts/tannin.md --type Reference --title "Tannin" --bundle mykb
okfctl node list --bundle mykb                                       # see the node you just made
okfctl index build mykb                                              # generate the reserved index.md files
okfctl index check mykb                                              # confirm the index is current
okfctl log append mykb --message "added tannin node"                # record the change
okfctl validate mykb                                                 # check against the OKF spec floor
okfctl bundle info mykb                                              # nodes: 1, reserved: 3, okf_version: 0.2

From here, okfctl search "tannin" mykb finds nodes lexically, okfctl graph export mykb dumps the link graph, and okfctl analyze mykb reports where the bundle is weak. Every command explains itself with okfctl <cmd> --help, including a runnable example.

Commands

One line each; run okfctl <cmd> --help for full detail and examples, or see the command reference.

Command	What it does
`bundle`	Scaffold (`init`) and summarize (`info`) an OKF bundle.
`node`	Author and inspect nodes: `new`, `show`, `list`, `edit`, `mv`, `rm`, `refresh`, `promote`.
`index`	Regenerate (`build`) and verify (`check`) the reserved per-directory `index.md`.
`log`	Append (`append`) and print (`show`) the reserved `log.md` change history.
`validate`	Check a bundle against the OKF spec floor; optionally overlay type-templates.
`lint`	Report curation-health findings (orphans, broken links, coverage gaps); `--strict` for CI.
`eval`	Measure KB-node trustworthiness (TACA): a deterministic Transparency gate + a spot-check sampler for Accuracy/Alignment/Calibration.
`analyze`	Report where a bundle is weak: freshness, clusters, gaps, connectivity, structure.
`search`	Core lexical + graph-neighborhood search (stdlib-only, no model or index).
`graph`	Export the concept-node link graph (`--format json\|dot`).
`serve`	Serve an interactive web visualization of the bundle graph.
`template`	List (`list`) and show (`show`) the type-templates a bundle declares.
`migrate`	Upgrade a bundle from OKF v0.1 to v0.2 (two-phase, consumer-agnostic).
`registry`	Manage named remote bundle sources — `git remote` for OKF bundles.
`connect`	Clone or fast-forward a remote bundle source into a local directory.
`plugin`	Discover (`list`) and install (`install`) `okfctl-<name>` plugins on `PATH`.
`config`	Get, set, and list okfctl configuration.
`completion`	Generate a shell completion script (bash, zsh, fish).
`version`	Print the okfctl version (also `okfctl --version`).

Semantic search over a bundle ships as the bundled okfctl-search plugin, invoked as okfctl search --semantic …. See the search guide.

Use as an agent plugin

This repo is an Agent Plugins 1.0.0 package: the root plugin.json bundles the four generic okfctl skills (okf-authoring, okf-curation-health, okf-migrate-plan, okf-semantic-search) as an installable unit for compatible agent clients (Copilot, Cursor, Codex, …). Harnesses that read repo instructions directly pick the same guidance up from AGENTS.md.

Not to be confused with okfctl plugin above — that command discovers and installs okfctl-<name> executable plugins (like okfctl-search) on your PATH. This section is about packaging okfctl's skills for an agent client, which is a different spec.

Prerequisite — install okfctl first. The skills shell out to the okfctl binary, and a plugin client does not bundle it. Install it onto your PATH before enabling the plugin (see Install):

brew install cwest/tap/okfctl

The manifest carries no hand-maintained version string: the authoritative version is the release tag, reported by okfctl version.

Learn more

User docs — concepts, task-oriented guides, and the full command reference live under docs/. Start with concepts, then the guides:
- Starting and authoring a bundle
- Keeping index.md current and fixing freshness drift — covers .okf-drift-ignore-revs.
- Curation health: lint, analyze, and --strict in CI — covers the semantic-lint checks and the vendored/derived skip policy.
- Search: core lexical/graph and the okfctl-search semantic plugin — covers model2vec setup.
- Migrating a v0.1 bundle to v0.2
- Remote sources: registry and connect
- Extending okfctl with plugins
Per-command help — okfctl <cmd> --help is authoritative and always matches the binary.
The spec — the authoritative OKF v0.2 specification.
For contributors — docs/PRD.md, the ADRs, and the dated plans/specs that record how and why the tool was built.

License

Apache-2.0. See LICENSE.