# okf-cli

> Command line and MCP server for working with Open Knowledge Format (OKF) catalogues. This is the documentation of the CLI, not of the OKF specification.

- [Command line and MCP server for OKF catalogues](https://rierek.github.io/okf-cli/): Command line and MCP server for working with Open Knowledge Format (OKF) catalogues
- [okf in brief: CLI and MCP server for OKF catalogues](https://rierek.github.io/okf-cli/overview/): okf is a command line and MCP server that searches, checks and refactors a markdown knowledge base of Open Knowledge Format (OKF) v0.2 bundles, for people and AI agents.
- [Agent onboarding: MCP server, skill and okf prime](https://rierek.github.io/okf-cli/overview/agent-onboarding/): Connect Claude Code, Codex, omp, opencode, Kimi Code, OpenClaw or Hermes to okf: okf install, MCP server, agent skill, okf prime, llms.txt.
- [OKF concepts: catalogue, bundle, concept and frontmatter](https://rierek.github.io/okf-cli/overview/concepts/): How an Open Knowledge Format catalogue is built: catalogue, bundle, concept, type, frontmatter, okf_version and the provenance fields okf checks.
- [Getting started with okf: search a Markdown knowledge base](https://rierek.github.io/okf-cli/overview/first-steps/): okf getting started: point okf at a catalogue, list its bundles, build the index, run okf find, read one concept and run okf check. Five steps on a test catalogue.
- [Install okf CLI: Homebrew, release binary or source build](https://rierek.github.io/okf-cli/overview/installation/): Install the okf CLI on macOS or Linux with Homebrew, a release binary or a source build, then check that it runs.
- [okf troubleshooting: command not found, completion, MCP server](https://rierek.github.io/okf-cli/overview/troubleshooting/): Fix okf command not found, TAB completion not working, MCP server errors and a missing search index.
- [Features](https://rierek.github.io/okf-cli/features/): OKF tooling features by activity: search, context bundles, tags, conformance checks, safe edits, canon blocks and setup.
- [Canon blocks: one source of truth for shared rules in markdown](https://rierek.github.io/okf-cli/features/canon-blocks/): Canon blocks keep one text in sync across many concepts. Write a rule once, materialise it with okf sync-insert, and see drift with okf sync-status.
- [Conformance checks](https://rierek.github.io/okf-cli/features/conformance-checks/): Validate markdown frontmatter and links: okf check scans a catalogue against the OKF v0.2 hard rules and local invariants.
- [Context bundles](https://rierek.github.io/okf-cli/features/context-bundles/): Context management for AI agents: a ctx bundle is a curated reading list in reading order, with live titles and token estimates.
- [Safe edits: rename markdown files and keep every link](https://rierek.github.io/okf-cli/features/safe-edits/): Rename or archive a concept, preview the diff first, and let okf update links in one step. Safe edits for a markdown knowledge base: okf rename, archive, dry run.
- [Markdown knowledge base search: okf find](https://rierek.github.io/okf-cli/features/search/): Ranked BM25 search over a Markdown knowledge base with okf find: FTS5 index, optional semantic search with embeddings, one --where filter.
- [Tag management and the TAGS.md registry](https://rierek.github.io/okf-cli/features/tags-and-registry/): Tag management for Markdown frontmatter: usage counts, fuzzy search, the TAGS.md registry, merge tags, and tag hygiene checks from the CLI.
- [Terminal UI for a Markdown knowledge base: okf tui](https://rierek.github.io/okf-cli/features/tui/): okf tui is a keyboard-first terminal UI: search a catalogue, filter, collect hits in a session buffer, hand them to an agent, record maintenance tasks. GIFs show every key.
- [okf use cases](https://rierek.github.io/okf-cli/use-cases/): okf use cases: five worked examples of agent context workflows and knowledge base upkeep, each with real output.
- [Define canon knowledge once and reuse it across projects](https://rierek.github.io/okf-cli/use-cases/define-canon-knowledge/): Canon knowledge in markdown: write a rule once in an owner concept, copy it with okf sync-insert, refresh copies with okf sync-update. Reusable rules across projects.
- [Migrate to OKF 0.2](https://rierek.github.io/okf-cli/use-cases/migrate-to-okf-0-2/): Migrate a catalogue to OKF 0.2 frontmatter with okf migrate: timestamp to generated, status rules, dry run first. Open Knowledge Format upgrade.
- [Onboard an AI agent to a knowledge base with okf prime](https://rierek.github.io/okf-cli/use-cases/onboard-agents/): Onboard an AI agent to your knowledge base: okf prime gives a fresh Claude Code or MCP session the catalogue map, okf ctx the pages that matter.
- [Organize large bundles: tags, renames, links, checks](https://rierek.github.io/okf-cli/use-cases/organize-large-bundles/): Keep a large markdown knowledge base consistent: tag cleanup, rename with link repair, fix broken links and run okf check. Every change shows a preview first.
- [Work with multiple knowledge bases: okf --root and config](https://rierek.github.io/okf-cli/use-cases/work-with-multiple-bundles/): Run one okf binary against several catalogues: pick one per call with --root, --global or a config file. Works for Obsidian vault folders too.
- [okf commands list](https://rierek.github.io/okf-cli/reference/commands/): okf command reference: all okf commands by purpose, as in okf --help, with global options.
- [okf build-index](https://rierek.github.io/okf-cli/reference/commands/okf-build-index/): (re)build the FTS5 lexical search index at <root>/.fts/fts.sqlite (local only, no network)
- [okf build-semantic-index](https://rierek.github.io/okf-cli/reference/commands/okf-build-semantic-index/): fill <root>/.tagvec/tag_vectors.sqlite's concept_emb table for every concept still missing a voyage-3-large embedding (NETWORK, requires VOYAGE_API_KEY)
- [okf index](https://rierek.github.io/okf-cli/reference/commands/okf-index/): catalogue TOC (bundle names + one-line descriptions), or one bundle's index.md
- [okf reindex](https://rierek.github.io/okf-cli/reference/commands/okf-reindex/): (re)generate marker-bounded index listings: index.md one level, index-map.md the whole subtree
- [okf reference](https://rierek.github.io/okf-cli/reference/): okf command reference: every command, the where filter, JSON output and exit codes, configuration, frontmatter and types, and the glossary.
- [okf archive](https://rierek.github.io/okf-cli/reference/commands/okf-archive/): move a concept into _archive/<bundle>/, or back with --restore (dry-run default)
- [okf check](https://rierek.github.io/okf-cli/reference/commands/okf-check/): conformance scan: §9 hard rules + local invariants
- [okf ctx](https://rierek.github.io/okf-cli/reference/commands/okf-ctx/): context bundles: curated, ordered reading lists per topic (`ctx` lists them, `ctx <slug>` shows one)
- [okf ctx add](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-add/): add one entry to a ctx bundle
- [okf ctx check](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-check/): validate ctx bundles
- [okf ctx create](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-create/): create a ctx bundle from paths and/or an import file
- [okf ctx drop](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-drop/): remove one entry from a ctx bundle
- [okf ctx edit](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-edit/): open a ctx bundle in $VISUAL/$EDITOR/vi and validate it
- [okf ctx inbound](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-inbound/): list the files that link to each entry
- [okf ctx list](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-list/): list ctx bundles with entry and required counts
- [okf ctx move](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-move/): reorder an entry or change its mode
- [okf ctx outbound](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-outbound/): list the links each entry points to
- [okf ctx read](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-read/): print the full content of every required entry
- [okf ctx remove](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-remove/): delete a ctx bundle and list files that still link to it
- [okf ctx rename](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-rename/): rename a ctx bundle and rewrite inbound links
- [okf ctx show](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-show/): list a ctx in reading order with live metadata and token estimates
- [okf ctx toc](https://rierek.github.io/okf-cli/reference/commands/okf-ctx-toc/): print the headings of every entry
- [okf find](https://rierek.github.io/okf-cli/reference/commands/okf-find/): hybrid ranked search: lexical FTS5/BM25 arm plus semantic arm
- [okf fix-crosslinks](https://rierek.github.io/okf-cli/reference/commands/okf-fix-crosslinks/): rewrite links to catalogue-root-absolute form (/bundle/subdir/concept.md)
- [okf fix-xml-tags](https://rierek.github.io/okf-cli/reference/commands/okf-fix-xml-tags/): wrap `<tag>`/`<tag>.<tag2>` placeholders in inline code
- [okf info](https://rierek.github.io/okf-cli/reference/commands/okf-info/): print catalogue schema docs (TYPES.md + PROPERTIES.md)
- [okf install](https://rierek.github.io/okf-cli/reference/commands/okf-install/): register okf, its agent skill, MCP server and shell completion with this machine's agents and shells (dry-run default; needs no catalogue)
- [okf list](https://rierek.github.io/okf-cli/reference/commands/okf-list/): list the complete, unranked set of concepts a required --where expression selects
- [okf merge-tags](https://rierek.github.io/okf-cli/reference/commands/okf-merge-tags/): merge/rename one or more tags into a target tag across concept frontmatter
- [okf migrate](https://rierek.github.io/okf-cli/reference/commands/okf-migrate/): migrate frontmatter to OKF 0.2: `timestamp` to `generated` (git), `status` per D37 (dry-run default)
- [okf normalize-tags](https://rierek.github.io/okf-cli/reference/commands/okf-normalize-tags/): convert inline `tags: [...]` fields to YAML block-list form (local convention)
- [okf prime](https://rierek.github.io/okf-cli/reference/commands/okf-prime/): one-shot agent onboarding: usage guide, command directory, catalogue state and bundle TOC
- [okf read](https://rierek.github.io/okf-cli/reference/commands/okf-read/): print one concept page
- [okf recent](https://rierek.github.io/okf-cli/reference/commands/okf-recent/): list the most recently created concepts, newest first
- [okf refs](https://rierek.github.io/okf-cli/reference/commands/okf-refs/): list inbound and outbound markdown links of a file
- [okf registry](https://rierek.github.io/okf-cli/reference/commands/okf-registry/): reformat registry entries of TAGS.md or TYPES.md (table or block form); prose stays
- [okf registry convert](https://rierek.github.io/okf-cli/reference/commands/okf-registry-convert/): rewrite every entry of one registry file in the target form
- [okf remove-tags](https://rierek.github.io/okf-cli/reference/commands/okf-remove-tags/): remove one or more tags from concept frontmatter (no merge target)
- [okf rename](https://rierek.github.io/okf-cli/reference/commands/okf-rename/): move a concept + rewrite every inbound/outbound link + reindex (dry-run default)
- [okf rewrite-path](https://rierek.github.io/okf-cli/reference/commands/okf-rewrite-path/): literal path-string rewrite across text files
- [okf sync-export](https://rierek.github.io/okf-cli/reference/commands/okf-sync-export/): print a canonical block's payload for materialisation elsewhere
- [okf sync-insert](https://rierek.github.io/okf-cli/reference/commands/okf-sync-insert/): materialise a canonical block inside a consumer concept (dry-run default)
- [okf sync-status](https://rierek.github.io/okf-cli/reference/commands/okf-sync-status/): drift report for every materialised canon block
- [okf sync-update](https://rierek.github.io/okf-cli/reference/commands/okf-sync-update/): re-materialise outdated consumer blocks from their canon owner (dry-run default)
- [okf tags](https://rierek.github.io/okf-cli/reference/commands/okf-tags/): list all tags with usage counts, or fuzzy-search candidate tags
- [okf toc](https://rierek.github.io/okf-cli/reference/commands/okf-toc/): print a concept's headings (default: h2 only)
- [okf tui](https://rierek.github.io/okf-cli/reference/commands/okf-tui/): keyboard-first terminal UI: search the catalogue, screen hits
- [okf verify](https://rierek.github.io/okf-cli/reference/commands/okf-verify/): record that a concept was checked against its sources
- [okf visualize](https://rierek.github.io/okf-cli/reference/commands/okf-visualize/): write a viz.html concept graph for a bundle (embeds every concept body; needs network for cytoscape/marked)
- [okf wikilinks](https://rierek.github.io/okf-cli/reference/commands/okf-wikilinks/): report Obsidian wikilinks ([[…]]) and whether each resolves to a concept
- [okf tui: terminal UI](https://rierek.github.io/okf-cli/reference/commands/tui/): okf tui opens a keyboard-first terminal UI on the catalogue root: search with result list and detail pane, keys, the [tui] settings and how to open it as a herdr popup.
- [Configuration: root resolution, .okf.toml and config.toml](https://rierek.github.io/okf-cli/reference/configuration/): How okf finds its catalogue, which keys .okf.toml and ~/.config/okf/config.toml read, and which environment variables matter (XDG config CLI).
- [Frontmatter and types: OKF fields and provenance](https://rierek.github.io/okf-cli/reference/frontmatter-and-types/): Frontmatter fields, the TYPES.md type vocabulary and the OKF v0.2 provenance fields generated, sources, verified and stale_after.
- [Glossary: catalogue, bundle, concept and other okf terms](https://rierek.github.io/okf-cli/reference/glossary/): Definitions of the okf terms: catalogue, bundle, concept, type, frontmatter, ctx bundle, canon block, registry, envelope, root, FTS index, semantic arm, dry run and apply.
- [JSON output and exit codes (machine-readable okf)](https://rierek.github.io/okf-cli/reference/json-output-and-exit-codes/): Reference for okf JSON output: the --json envelope, exit-code classes 0 to 5 and failure shapes for scripts, CI and agents that need a machine-readable CLI.
- [Where filter: the okf --where expression](https://rierek.github.io/okf-cli/reference/where-filter/): Reference for the okf where filter: grammar, fields, operators, precedence, errors and examples for filtering Markdown frontmatter with okf find and okf list.
- [okf blog](https://rierek.github.io/okf-cli/blog/): okf blog: field notes on context management, tag hygiene and canon knowledge in a knowledge base.
- [Canon in the catalogue](https://rierek.github.io/okf-cli/blog/canon-in-the-catalogue/): One truth in one place. A shared canon in the catalogue gives every project the same rules, and okf keeps the copies in step.
- [Context management with work-in-progress](https://rierek.github.io/okf-cli/blog/context-management-with-work-in-progress/): An agent needs a small, targeted context, not a full dump. Work in a topic folder, promote what lasts into the catalogue and hand it over with ctx.
- [Tag hygiene](https://rierek.github.io/okf-cli/blog/tag-hygiene/): Tags only help while the vocabulary stays small and controlled. Register tags in TAGS.md, validate them and block unregistered tags in CI.
- [Releases](https://rierek.github.io/okf-cli/releases/): What changed in each okf release.
- [okf 0.2.5: okf as a single Go binary](https://rierek.github.io/okf-cli/releases/v0-2-5/): The okf CLI is one static Go binary: no Python, no uv, same commands.
- [okf 0.2.6: okf tui](https://rierek.github.io/okf-cli/releases/v0-2-6/): okf tui is a keyboard-first terminal UI to search a catalogue, collect hits and hand them to an agent. Homebrew now installs the Go binary.
- [Known limitations](https://rierek.github.io/okf-cli/known-limitations/): Open defects and limits of okf, by short ID, with effect and workaround.
- [Contribute to okf: build from source and run the tests](https://rierek.github.io/okf-cli/contribute/): Report bugs, build okf from source, run the tests, change the docs site, license and credit.
- [About okf: Open Knowledge Format tooling](https://rierek.github.io/okf-cli/about/): What okf is, where it comes from and how it relates to the Open Knowledge Format (OKF) specification.