---
slug: "pi-okf"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/kaishin/pi-okf@main/README.md"
repo: "https://github.com/kaishin/pi-okf"
source_file: "README.md"
branch: "main"
---
# pi-okf

CLI for creating and validating [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
| **Spec (raw)** | [raw SPEC.md](https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/okf/SPEC.md) |
| **OKF directory & overview** | [GoogleCloudPlatform/knowledge-catalog → okf/](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) |
| **Sample bundles** | [samples/](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/samples) |
| **Launch announcement** | [How the Open Knowledge Format can improve data sharing](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) (Google Cloud blog, June 12, 2026) |
| **Product** | [Google Cloud Knowledge Catalog](https://cloud.google.com/products/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.

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

## Install

```bash
# 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

```bash
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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):

| 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.

```bash
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

```bash
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

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

## Pi package (optional)

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

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

For an ongoing authoring session, use the Pi `okf_diff` tool (or `/okf-diff [path]`) before `okf_inspect`. It lists staged, unstaged, and untracked files relative to `HEAD`, so the agent can read the changed sources before updating `/okf`. The tool accepts `base` (for example, `origin/main`), `path`, and `includeUntracked` when a broader or narrower change window is needed.

At the end of a meaningful session, call the `okf_capture` tool (or `/okf-capture [bundle-path] [summary...]`) to append a dated entry with decisions, changes, and open questions to `/okf/log.md`. Pass structured args to the tool when bullets are needed; the slash command stays light and treats everything after the bundle path as the summary.

## Contributing

Issues and PRs: [github.com/kaishin/pi-okf](https://github.com/kaishin/pi-okf).

When changing validation behavior, keep §9 soft-constraint rules as warnings unless the official [SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) hardens them.

## License

[MIT](https://github.com/kaishin/pi-okf/tree/HEAD/LICENSE) © 2026 Kaishin.

OKF itself is an open specification published by Google Cloud; see the [knowledge-catalog](https://github.com/GoogleCloudPlatform/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.