pi-okf

CLI for creating and validating Open Knowledge Format (OKF) bundles.

OKF is Google’s open, Markdown-first format for portable knowledge — a directory of .md files with YAML frontmatter. No required manifest. This tool implements create/validate/index/pack against the v0.1 Draft spec (SHA pinned in package.json).

Official OKF documentation (Google)

| Resource | Link | |---|---| | Specification (canonical) | okf/SPEC.md | | Spec (raw) | raw SPEC.md | | OKF directory & overview | GoogleCloudPlatform/knowledge-catalog → okf/ | | Sample bundles | samples/ | | Launch announcement | How the Open Knowledge Format can improve data sharing (Google Cloud blog, June 12, 2026) | | Product | Google Cloud Knowledge Catalog |

pi-okf is an independent community CLI. It is not an official Google product. Prefer the links above when the format itself is in question.

pi-okf --spec-info   # prints pinned OKF version + SHA used by this release

Install

# from source
git clone https://github.com/kaishin/pi-okf.git
cd pi-okf
npm install
npm run build
npm link                 # optional: put `pi-okf` on PATH

# or run without linking
npx tsx src/cli.ts <command>

Requires Node.js ≥ 18.

Commands

pi-okf validate <bundle-path> [--strict] [--json] [--fail-on-warnings]
pi-okf init <bundle-name> [--dir <path>]
pi-okf index <bundle-path> [--write]
pi-okf pack <bundle-path> [--out <path>] [--no-okf]
pi-okf inspect <file.md> [--json]
pi-okf capture <bundle-path> --summary <text> [--title <text>] [--decision <text>...] [--change <text>...] [--question <text>...]
pi-okf --spec-info [--json]
pi-okf --help | --version

validate

Walks the bundle tree and checks normative OKF rules from the official spec:

| Severity | Rule | Behavior | |---|---|---| | Hard | §2.2 item 1 — frontmatter must be parseable YAML when present | error → exit 1 | | Hard | §2.2 item 2 — non-empty type when frontmatter present | error → exit 1 | | Hard | §6 — index.md must not have frontmatter | error → exit 1 | | Soft | Missing frontmatter on plain docs | warn (use --strict to fail) | | Soft | §9 — unknown type, unknown keys, broken links, missing index.md | warn only |

§9 Conformance (normative for consumers): consumers MUST NOT reject a bundle solely because of missing optional fields, unknown type values, unknown extra frontmatter keys, broken cross-links, or missing index.md. This CLI treats those as warnings (exit 2), never hard failures.

Exit codes:

| Code | Meaning | |---|---| | 0 | Clean — no errors or warnings | | 1 | Hard error | | 2 | Soft warnings only |

init

Scaffolds index.md, log.md, and an example concept.md with full frontmatter.

index

Generates index.md content grouped by frontmatter type. Pass --write to overwrite files.

pack

Zips the bundle to <name>.okf (or .zip with --no-okf). Uses system zip when available, otherwise adm-zip.

inspect

Dumps frontmatter and structure for a single .md file.

capture

Appends a dated entry to the bundle's log.md summarising the current session: a title, a one-line summary, and optional bulleted lists for decisions, changes, and open questions. When called, the command also runs okf validate and prints the result so you can spot any conformance errors introduced by the new entry.

pi-okf capture okf/ \
  --summary "Migrated the subscription model docs to the new schema" \
  --title "Subscription model migration" \
  --decision "Treat the application schema as the source of truth." \
  --decision "Keep payments staging in the ledger tables, not the app." \
  --change "Rewrote tables/subscriptions.md to reference the new entities." \
  --question "Confirm the retention policy with the data team."

Repeated --decision, --change, and --question flags accumulate into bulleted lists. Entries for the same day are grouped under a single ## YYYY-MM-DD heading; the most recent capture sits at the top of that group, and newer days sit above older ones in the log.

Exit codes:

| Code | Meaning | |---|---| | 0 | Capture succeeded; no hard validation errors | | 1 | Hard validation error in the bundle (e.g. broken log.md structure) |

Soft validation warnings (such as a missing root index.md) are reported but never block capture.

Examples

pi-okf validate examples/minimal-bundle/          # exit 0, prints OK
pi-okf validate examples/broken-bundle/           # exit 1, cites §2.2
pi-okf validate examples/soft-violation-bundle/   # exit 2, warnings only
pi-okf init my-bundle && pi-okf validate my-bundle/
pi-okf pack examples/minimal-bundle/ --out /tmp/minimal.okf
pi-okf capture my-bundle/ --summary "Shipped the capture command" --decision "Keep /okf-capture args unstructured"

Spec pin

| Field | Value | |---|---| | Version | 0.1 Draft | | Canonical URL | https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md | | SHA | ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a (package.json → okf.specSha) |

Development

npm install
npm test          # vitest
npm run check     # tsc --noEmit
npm run build     # emit dist/

Pi package (optional)

This repo also ships a Pi extension (extensions/okf.ts) and skill for agent workflows. The CLI is the primary interface and does not require Pi.

pi install npm:pi-okf
# or develop locally
pi -e /absolute/path/to/pi-okf

Shared slash commands (aligned with claude-okf / opencode-okf)

The authoring aliases /okf-init, /okf-update, and /okf-compact are discovered as package prompt templates, then transformed by the extension into an invocation of the bundled okf skill. Pi renders the skill instructions as a compact, expandable skill block instead of inserting the full generated workflow as a visible user message. Deterministic commands such as /okf-validate remain extension commands.

You can also invoke the skill directly, for example /skill:okf update session.

| Command | Role | |---|---| | /okf-init | Inspect the repo and author an evidence-backed bundle | | /okf-update [session\|diff] | Update concepts/indexes from full repo (no arg), git diff, or this session | | /okf-validate | Report conformance errors and quality warnings | | /okf-compact [all] | Prune logs, or whole bundle (concepts, indexes, logs) with all |

/okf-update hard args:

| Args | Source | |---|---| | (none) or free-form focus | Full repository evidence | | diff [ref] [focus…] | Git changes via okf_diff (default HEAD) | | session [focus…] | Conversation + work — concepts/indexes first, not log-only |

Shared tools

| Tool | Role | |---|---| | okf_validate | Deterministic OKF v0.1 validation | | okf_diff | Git changed-file inventory (used by /okf-update diff) | | okf_capture | Append a dated log entry when log is the right place |

Pi-only helpers

| Command / tool | Role | |---|---| | okf_init | Empty bundle scaffolding only (no concepts) | | /okf-inspect / okf_inspect | Inventory likely product/schema/analytics sources |

Examples:

/okf-update
/okf-update diff origin/main
/okf-update session architecture decisions

To prune accumulated knowledge, run /okf-compact:

/okf-compact
/okf-compact aggressive
/okf-compact all
/okf-compact all aggressive
/okf-compact conservative keep the migration decisions, drop everything before June

| Args | Scope | |---|---| | (none) or aggressiveness/focus only | logs only | | all [aggressiveness] [focus…] | all — concepts, indexes, and logs |

Optional aggressiveness: conservative | balanced (default) | aggressive.

Contributing

Issues and PRs: github.com/kaishin/pi-okf.

When changing validation behavior, keep §9 soft-constraint rules as warnings unless the official SPEC.md hardens them.

License

MIT © 2026 Kaishin.

OKF itself is an open specification published by Google Cloud; see the knowledge-catalog repository for Google’s terms on the format, samples, and reference tooling. This CLI is a separate project and is not affiliated with or endorsed by Google.