okf is a Go CLI toolkit for the Open Knowledge Format: agentic-first, JSON-native, vendor-neutral. A single binary alternative to Google's Python/Gemini-locked reference implementation.
okf v0.2.0 implements the new OKF v0.2 spec end to end: provenance, trust, lifecycle, and attested computations, all parsed, validated, and surfaced as JSON your agent can branch on. Verified against every reference bundle in Google's knowledge-catalog repository with zero errors.
verified
events: unverified
, machine-confirmed
, or human-reviewed
. okf list
and okf show
expose it, so an agent can decide what to trust before it acts.sources
with per-source credibility signals: author, usage count, last modified. Body footnotes join into source ids for per-claim attribution, and okf validate
checks the join both ways.status
(draft, stable, deprecated) and stale_after
make freshness a plain date comparison. Validation flags a stale concept the day it expires; nothing silently rots.runtime
, typed parameters
, an executor
, and a deterministic attester
. okf validates the full contract, including that every contract path actually exists in the bundle.
$ okf list ./bundles/finance
{
"concepts": [
{"id":"computations/revenue", "type":"Attested Computation", "status":"stable", "trust_tier":"human-reviewed"},
{"id":"metrics/margin-legacy", "type":"Metric", "status":"deprecated", "trust_tier":"machine-confirmed"}
]
}
$ okf validate ./old-bundle
{
"valid": true,
"warnings": 1,
"findings": [{"severity":"WARN", "message":"frontmatter: legacy 'timestamp' is superseded by 'generated.at' in OKF v0.2 (§13.1)"}]
}
Google's reference OKF implementation is Python + Gemini + BigQuery, vendor-locked to Google's cloud. okf
is the vendor-neutral alternative: a single Go binary that works anywhere, speaks JSON natively, and is designed to be driven by any AI agent, not just Gemini.
--help
text, guess at flags, screen-scrape stdout. Errors are English sentences you can't reliably branch on. Every agent integration is bespoke prompt engineering.okf schema
once: a JSON manifest of every command, its args, output format, and exit codes. Drive the CLI from that spec. Branch on .error.kind
. JSON is the default, not an opt-in flag.Built test-first (88 tests), Go stdlib-only, Apache 2.0. Every command outputs structured JSON on stdout by default. No --json
flag, no screen-scraping.
Emits a complete JSON manifest of every command: name, description, flags, args, stdout format, exit codes. One call and an agent knows the full CLI surface. This is the moat.
Prints version info as JSON. Agents can check compatibility before driving the rest of the CLI.
Scaffolds a new empty OKF bundle with standard subdirectories (tables, datasets, playbooks), a root index.md
, and a .gitignore
. The starting point for an AI-driven documentation pipeline.
Generates index.md
files into every directory for progressive disclosure per OKF spec §8, preserving the bundle's okf_version
declaration. Agents navigate level by level instead of the entire bundle.
Checks every concept against OKF v0.2: required frontmatter, cross-links, the provenance, trust, and lifecycle families, attested-computation contracts, and legacy v0.1 constructs. Exits 1 if any errors are found. The CI quality gate.
Same checks as validate but only emits warnings. Errors are suppressed, so it exits 0 even with warnings. Use it to flag missing recommended fields without failing a build.
Lists every concept document with its ID, type, title, lifecycle status, and trust tier as JSON. The inventory query: what's in this bundle, and how much should I trust it?
Filters concepts by --tag
, --type
, or --text
. Find stale concepts, filter by category, or locate everything tagged auth
, all as structured JSON.
Returns a single concept's full content: frontmatter, markdown body, trust tier, staleness, provenance sources, and the attested-computation contract when present, all as JSON. The deep-read command.
Builds the directed cross-link graph from markdown links plus v0.2 derivation edges (sources, computations, executors, attesters) and prints nodes, edges, density, and summary statistics. Find orphan concepts and verify structure.
Lists every concept that links to a given concept: reverse-link lookup. Answer "who depends on this?" without grepping the entire bundle.
"Agentic first" means an external AI can discover and drive the CLI via okf schema
, not that the CLI calls an LLM internally. Everything an agent needs is built into the binary itself.
// 1. Discover: load the schema manifest
$ okf schema
{
"name": "okf",
"description": "Go CLI toolkit for the Open Knowledge Format (OKF)",
"commands": [
{"name":"schema", "stdout":"json", "exit_codes":[0,4]},
{"name":"validate", "stdout":"json", "exit_codes":[0,1,2,4]},
{"name":"graph", "stdout":"json", "exit_codes":[0,2,4]}
// ...8 more
]
}
// 2. Drive: JSON on stdout, diagnostics on stderr
$ okf graph ./my-bundle
{
"command": "graph",
"node_count": 3,
"edge_count": 3,
"density_pct": 50,
"isolated": 0,
"nodes": [{"id":"tables/events_","type":"BigQuery Table"}],
"edges": [{"from":"datasets/ga4","to":"tables/events_"}]
}
// 3. Recover: typed error envelopes, not English sentences
$ okf validate ./broken-bundle
{
"error": {
"kind": "validation",
"code": 400,
"reason": "validationError",
"message": "broken link: [Users] -> users.md (concept tables/users not found)"
}
}
// exit code: 1 -> agent parses findings, fixes, re-validates
// 4. Branch: exit codes map 1:1 to error kinds
| Code | Kind | Agent Strategy |
|---|---|---|
| 0 | success | Parse stdout JSON, continue |
| 1 | validation | Parse findings, fix the bundle, re-run |
| 2 | io | Check filesystem / paths, surface to caller |
| 3 | internal | Escalate to user, unexpected error |
| 4 | usage | Fix flags/args from schema, retry |
v0.2.0 released, cosign-signed, SBOM-included. One binary, no runtime dependencies.
brew install okfcli/okf/okf
go install github.com/okfcli/okf/cmd/okf@latest
git clone https://github.com/okfcli/okf.git
cd okf && make build
./okf --help
Then scaffold a bundle, add concepts, and validate:
$ okf init ./my-bundle
{"command":"init","bundle":"./my-bundle","created":true}
$ okf validate ./my-bundle
{"bundle":"./my-bundle","command":"validate","valid":true,"errors":0,"warnings":0,"findings":[]}
$ okf index ./my-bundle
$ okf graph ./my-bundle
$ okf search ./my-bundle --type Table --tag revenue
Schema-discoverable. JSON-native. Vendor-neutral. One Go binary.