okf — the CLI your AI agent drives to manage your knowledge graph

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 (35 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 — progressive disclosure per OKF spec §6. Agents navigate level by level instead of loading the entire bundle.

Validate & Quality

✅

okf validate

Checks every concept for required frontmatter (type), recommended fields (title, description, tags), non-empty body, and valid cross-links. Exits 1 if any errors are found. The CI quality gate.

🧹

okf lint

Same checks as validate but only emits warnings — errors are suppressed. 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, and title as JSON. The inventory query — what's in this bundle?

🔍

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 — ID, file path, frontmatter (type, title, description, resource, tags), and markdown body — as JSON. The deep-read command.

Graph & Relationships

🕸️

okf graph

Builds the directed cross-link graph from concept markdown links and prints nodes, edges, density, and summary statistics. Find orphan concepts and verify cross-link 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

okf is pre-v1 — no release tarballs or Homebrew yet. Install via Go or build from source. One binary, no runtime dependencies.

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