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 targets OKF v0.2 (with legacy v0.1 metadata tolerated via migration warnings).

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 package + OKF version metadata

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 OKF v0.2 producer rules (aligned with opencode-okf):

Severity	Rule	Behavior
Hard	Concept frontmatter must be parseable YAML with non-empty type	error → exit 1
Hard	Root index.md frontmatter (when present) must declare okf_version	error → exit 1
Hard	Nested index.md must not have frontmatter; indexes need heading + link bullets	error → exit 1
Hard	log.md structure (title, date groups newest-first, list entries)	error → exit 1
Hard	Attested Computation requires non-empty runtime	error → exit 1
Soft	Recommended title / description / tags / generated	warn only
Soft	Legacy timestamp (migrate to generated: { by, at })	warn only
Soft	Provenance/trust/lifecycle shape (verified, status, sources, …)	warn only
Soft	Broken internal links	warn only

Exit codes:

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

init

Scaffolds index.md (with okf_version: "0.2"), log.md, and an example concept.md using generated: { by, at }.

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 validation and prints the result.

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." \
  --change "Rewrote tables/subscriptions.md to reference the new entities." \
  --question "Confirm the retention policy with the data team."

Examples

pi-okf validate examples/minimal-bundle/          # exit 0, prints OK
pi-okf validate examples/broken-bundle/           # exit 1
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"

Spec target

Field	Value
Version	0.2
Canonical URL	https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
Live fetch	okf_spec tool / fetchOKFSpec() reads the raw SPEC.md and extracts **Version …**

Development

npm install
npm test          # vitest
npm run check     # tsc --noEmit
npm run build     # emit dist/
npm run test:pi   # node:test harness for the Pi extension

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 opencode-okf)

The authoring aliases /okf-init, /okf-update, /okf-upgrade, and /okf-compact are discovered as package prompt templates, then transformed by the extension into an invocation of the bundled okf skill. 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-upgrade	Migrate the entire bundle to the latest fetched specification
/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_spec	Fetch the authoritative current OKF specification
okf_validate	Deterministic OKF v0.2 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
okf_init	Empty bundle scaffolding only (no concepts)
okf_inspect	Inventory likely product/schema/analytics sources

Examples:

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

To prune accumulated knowledge, run /okf-compact:

/okf-compact
/okf-compact aggressive
/okf-compact all
/okf-compact all aggressive

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 optional metadata and broken links 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.