New in v0.2

Trust is now a first-class field

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.

TRUST TIERS

Every concept now gets a derived tier from its 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.

PROVENANCE

Concepts carry 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.

LIFECYCLE

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.

ATTESTED COMPUTATIONS

A new concept type carries a sanctioned computation: runtime, typed parameters, an executor, and a deterministic attester. okf validates the full contract, including that every contract path actually exists in the bundle.

# Trust and lifecycle, surfaced as JSON
$ 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"}
  ]
}

# v0.1 bundles still work: legacy fields fall back, with migration warnings
$ 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)"}]
}

Why okf exists

Vendor-neutral OKF tooling for any AI agent on any provider

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.

THE PROBLEM

The only reference OKF tooling requires Python, a Gemini API key, and BigQuery. Agents that don't run on Google's stack can't participate. The format is open, but the tooling isn't.

THE OLD WORKAROUND

Parse --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.

THE OKF WAY

Load 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.

THE RESULT

An agent that can discover, drive, and recover from okf without any prompt engineering. The schema IS the prompt. The error envelope IS the branching logic. The exit code IS the retry strategy. One binary, zero dependencies.

What's inside

11 commands, one binary, zero runtime dependencies

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.

Schema & Discovery

📐

okf schema

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.

🔢

okf version

Prints version info as JSON. Agents can check compatibility before driving the rest of the CLI.

Create & Structure

🚀

okf init

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.

📇

okf index

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 loading the entire bundle.

Validate & Quality

✅

okf validate

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.

🧹

okf lint

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.

Explore & Query

📋

okf list

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?

🔍

okf search

Filters concepts by --tag, --type, or --text. Find stale concepts, filter by category, or locate everything tagged auth, all as structured JSON.

📄

okf show

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.

Graph & Relationships

🕸️

okf graph

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.

🔗

okf backlinks

Lists every concept that links to a given concept: reverse-link lookup. Answer "who depends on this?" without grepping the entire bundle.

The agentic-first principle

Four primitives. Zero ambiguity.

"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

Get started

Install in 30 seconds

v0.2.0 released, cosign-signed, SBOM-included. One binary, no runtime dependencies.

Homebrew (macOS / Linux)

brew install okfcli/okf/okf

Go install

go install github.com/okfcli/okf/cmd/okf@latest

Build from source

git clone https://github.com/okfcli/okf.git
cd okf && make build
./okf --help

Then scaffold a bundle, add concepts, and validate:

# Create a new bundle
$ okf init ./my-bundle
{"command":"init","bundle":"./my-bundle","created":true}

# Write concept .md files into tables/, datasets/, playbooks/ ...

# Validate the bundle against the OKF spec
$ okf validate ./my-bundle
{"bundle":"./my-bundle","command":"validate","valid":true,"errors":0,"warnings":0,"findings":[]}

# Generate index.md files for progressive disclosure
$ okf index ./my-bundle

# Emit the knowledge graph as JSON
$ okf graph ./my-bundle

# Search by tag, type, or text
$ okf search ./my-bundle --type Table --tag revenue

⬇ View on GitHub Read the docs →

The CLI your AI agent drives to manage your knowledge graph