okf-cli — Open Knowledge Format tooling

Converts plain markdown into OKF-conformant knowledge bundles. Domain experts write the content, okf bundle generates frontmatter, type, timestamps, and index files.

Also validates bundles, lists concepts, reads concepts by ID, and reports version.

Install

uv tool install okf-cli

Dev quickstart

uv sync
uv run okf --help
uv run okf --version

Global options: --version, --help.

Commands

okf bundle — convert plain markdown to OKF bundle

okf bundle <input-dir> [output-dir] [--default-type <name>] [--force] [--strict]

okf bundle example --default-type reference          # → example_knowledge_base/
okf bundle example bundled --default-type reference --force --strict

.okfignore: put in input-dir root; one bundle-relative .md path per line. Exact match only (no glob).

Link checking: scans body links to local .md targets. Missing or out-of-bundle links warn by default, fail with --strict.

okf list — list concepts in a bundle

okf list <directory>

Prints a table of concepts with ID, type, title, and description. Requires valid OKF bundle.

okf list example_knowledge_base/
# ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━┓
# ┃ ID             ┃ Type     ┃ Title  ┃ Description ┃
# ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━┩
# │ datasets/sales │ datasets │ Sales  │ Sales data. │
# │ tables/orders  │ tables   │ Orders │ One row.    │
# └────────────────┴──────────┴────────┴─────────────┘

okf read — read a concept by ID

okf read <directory> <concept-id>

Prints full concept contents (frontmatter + body). Concept IDs as printed by okf list. Guards against path traversal.

okf validate — check OKF conformance

okf validate <directory>

Checks OKF v0.1 §9 conformance: frontmatter required, type required, reserved filenames follow spec structure, UTF-8 required.

okf validate example_knowledge_base/
# 16 files: 16 ok

Input format

Strict (recommended)

# Title

> Description

Lenient fallback

Files without strict format are bundled best-effort: title omitted if absent, description synthesized from first 80 chars of body.

Root files use --default-type, defaulting to the input directory name. See example/ for sample structure.

Output

Each concept becomes a markdown file with YAML frontmatter:

---
type: "tables"
title: "Customer Orders"
description: "One row per completed customer order across all channels."
timestamp: "2026-07-04T15:06:51+00:00"
---

Original body preserved as-is.

Every directory gets an index.md listing files and subdirs.

OKF Conformance

Generated bundles conform to OKF v0.1 (§9): frontmatter required, non-empty type, reserved filenames follow spec structure.

Project layout

okf-cli
├── .github/workflows/test.yml  # CI
├── AGENTS.md                   # Contributor context for AI agents
├── OKF_SPEC.md                 # OKF specification
├── README.md                   # This file
├── openwiki/                   # Contributor docs (architecture, workflows, etc.)
├── pyproject.toml              # uv-managed Python project
├── skills/                     # Optional skill definitions
├── uv.lock                     # uv lockfile
├── src/okf/
│   ├── cli.py                  # Typer entrypoint
│   ├── api.py                  # Programmatic Python API
│   ├── core.py                 # Shared parsing/formatting
│   └── commands/               # bundle, list, read, validate
├── tests/                      # pytest suite
└── example/                    # Sample input markdown

For contributor guidance, see AGENTS.md and openwiki/quickstart.md.