OKF Graph

Explore and validate Open Knowledge Format (OKF) bundles from your terminal.

okf-graph turns the Markdown links in an OKF bundle into a directed graph. Use it to find broken links, inspect individual concepts, explore relationships, and understand the structure of a knowledge bundle.

Quick start

Install Bun first. The examples use npx to run the latest published version without installing it globally.

npx okf-graph@latest graph neighbors \
  https://github.com/lloydrichards/proj_okf-graph/tree/main/examples/house-plants-okf \
  propagation/leaf-cuttings

An OKF bundle, like the included house-plants-okf, is a directory of Markdown concept files with YAML frontmatter. Links between those files express relationships as a directed graph.

Explore a bundle

# Use the example bundle for the commands below
BUNDLE="https://github.com/lloydrichards/proj_okf-graph/tree/main/examples/house-plants-okf"

# Read a concept and explore its local graph interactively
npx okf-graph@latest concept "$BUNDLE" foundations/houseplant --interactive

# Print a concept's neighbors directly
npx okf-graph@latest graph neighbors "$BUNDLE" foundations/houseplant

# Validate the structure and links in your own bundle
npx okf-graph@latest validate path/to/your-bundle

foundations/houseplant is a concept ID: the path to its Markdown file inside the bundle, without the .md extension. Run npx okf-graph@latest --help to discover commands, then npx okf-graph@latest <command> --help for options such as machine-readable JSON output.

Install globally

Install the command if you use it regularly:

npm install --global okf-graph
okf-graph --help

Commands accept local directories and GitHub tree URLs like the example above.

Give an agent the OKF skill

Print the skill's Markdown for an LLM to read directly:

npx okf-graph@latest skill read

Install the same skill in the current repository:

npx okf-graph@latest skill write

The command writes .agents/skills/okf/SKILL.md. Use --path <directory> to select another repository. An existing skill is preserved unless you pass --force.

Learn more

• okf-graph on npm
• Open Knowledge Format specification
• Open Knowledge Format on GitHub
• edu_effect-okf, the learning project that preceded this CLI

Development

Clone the repository, install dependencies with Bun, and run the CLI from the repository root:

bun install
bun start -- --help
bun start -- graph path examples/house-plants-okf foundations/houseplant care/watering
bun test

The repository includes examples/house-plants-okf, a sample bundle for local exploration.

Explore other OKF bundles

The official Open Knowledge Format repository includes several OKF v0.2 bundles covering different domains and graph shapes:

• GA4 — Google Analytics e-commerce data, events, and metrics.
• Stack Overflow — a larger, densely connected public dataset.
• Bitcoin — blocks, transactions, inputs, and outputs.
• Acme Retail — metrics, policies, attested computations, and bundle history.

Pass any bundle URL directly to okf-graph:

npx okf-graph@latest validate \
  https://github.com/GoogleCloudPlatform/open-knowledge-format/tree/main/bundles/acme_retail

License

MIT