Search, check, refactor. Your OKF catalogue.

Search, check, refactor. Your OKF catalogue.

okf-cli is the command line for catalogues of Open Knowledge Format (OKF) v0.2 bundles: Markdown files with YAML frontmatter. Humans read them, agents query them, scripts check them.

• One static binary
• CLI and MCP server
• Made for AI agents

Install okf-cliExplore features

~/kc · okf check

$ okf check
ERROR    kc/ctx/dead-entry    _ctx/legacy.md  (dead entry: handbook/ops/gone.md)
ERROR    okf/frontmatter/parseable handbook/broken-yaml.md  (no parseable frontmatter: did not find expected ',' or ']' (line 3, column 9))
ERROR    okf/trust/generated  handbook/wiki-notes.md  (`generated` has no non-empty `by`)
ERROR    okf/lifecycle/status handbook/wiki-notes.md  (`status` is `maybe-later`, not draft, stable or deprecated)
ERROR    okf/type/reserved-no-type recipes/readme.md  (reserved file must not carry `type`)
ERROR    kc/supersede/resolves recipes/salad.md  (superseded_by target does not resolve: recipes/soup)

Words first. Meaning when words fail.

WordsMeaning

The lexical arm ranks by the words in your query. It runs locally on an FTS5 index and needs no network. No word of this query appears in the Bread page, so the top hit is Gazpacho.

~/kc · okf find 'kneading and proofing' --limit 2

$ okf find 'kneading and proofing' --limit 2
note: semantic arm skipped (.tagvec cache/concept embeddings absent) — lexical results only
------
rank: 1
title: Gazpacho
type: Recipe
path: recipes/seasonal/gazpacho
description: Cold tomato soup
body-snippet: # Gazpacho Blend tomatoes, cucumber and peppers.…
provenance: lexical
------
rank: 2
title: Recipes overview
type: Concept
path: recipes/overview
description: Overview of the recipes
body-snippet: …, [bread](/recipes/bread.md), [soup](soup.md) and [[salad]].…
provenance: lexical
------

With embeddings, the semantic arm takes over when the lexical top hit lacks a clear margin. It says so, and provenance names the arm of every hit.

~/kc · okf find 'kneading and proofing' --limit 2

$ okf find 'kneading and proofing' --limit 2
note: semantic arm owns this ranking (lexical top-1 lacked a clear margin)
------
rank: 1
title: Bread
type: Recipe
path: recipes/bread
description: Bread with a long rise
body-snippet: # Bread ## Steps Mix, rise, bake. Related: [pasta](pasta.md).…
provenance: semantic
------
rank: 2
title: cooking
type: Context
path: _ctx/cooking
description: Cooking basics
body-snippet: # cooking | pos | mode | path | comment | |---|---|---|---| | 1 | pflicht | [bread](/recipes/bread.md) | | | 2 | pflicht | [pasta](/reci…
provenance: semantic
------

The whole catalogue. Or one bundle.

All bundlesOne bundle

okf find searches every bundle under the catalogue root. Two bundles answer here.

~/kc · okf find overview --limit 2

$ okf find overview --limit 2
------
rank: 1
title: Handbook overview
type: Concept
path: handbook/overview
description: Overview of the handbook
body-snippet: # Overview The handbook explains the [getting started guide](getting-started.md).…
provenance: lexical
------
rank: 2
title: Recipes overview
type: Concept
path: recipes/overview
description: Overview of the recipes
body-snippet: # Overview See [pasta](pasta.md), [bread](/recipes/bread.md), [soup](soup.md) and [[salad]].…
provenance: lexical
------

One --where filter narrows the answer to a bundle, a type, a tag or a date. Every arm applies it before it ranks.

~/kc · okf find overview --where 'path ~ recipes/' --limit 2

$ okf find overview --where 'path ~ recipes/' --limit 2
------
rank: 1
title: Recipes overview
type: Concept
path: recipes/overview
description: Overview of the recipes
body-snippet: # Overview See [pasta](pasta.md), [bread](/recipes/bread.md), [soup](soup.md) and [[salad]].…
provenance: lexical
------

Hand agents the right pages.

~/kc · okf ctx show onboarding

$ okf ctx show onboarding
ctx onboarding — Read this first on day one

required — read in this order:
  1. ~/kc/handbook/getting-started.md  [Guide] Getting started  ~158 tok
     First steps: accounts, tools, and where to find things
  2. ~/kc/handbook/glossary.md  [Concept] Glossary  ~62 tok
     Terms used here: "bundle" and "concept"
  3. ~/kc/handbook/ops/deploy.md  [Runbook] Deploy  ~150 tok
     How to deploy: build, ship, verify

Preview first, then write.

~/kc · okf rename

okf rename \1  recipes/soup.md \2  recipes/broth.md3

Moves a concept and its links

The concept to move

Prints a diff. --apply writes it

1. Moves a concept and its links
2. The concept to move
3. Prints a diff. --apply writes it

Read about safe edits

Built for humans, agents and programs.

Markdown for humans

A catalogue is a folder of Markdown files. Read it, edit it, diff it like code.

MCP and CLI for agents

okf install registers an MCP server and a skill. okf prime onboards a fresh session in one call.

JSON for programs

Every command answers --json with one envelope, and every failure has an exit code that names its class.

Your catalogues

--root points one binary at any catalogue, so private, project and shared bundles stay apart.

Anchored to the spec

okf-cli follows the OKF specification and is adapted when it changes.