Okf CLI

okf CLI User Manual

okf converts plain markdown directories into Open Knowledge Format (OKF) bundles — structured knowledge bases with YAML frontmatter, auto-generated indexes, and cross-link support.

Installation

Requires Python 3.11+ and uv:

uv tool install okf-cli
okf --version

Upgrade:

uv tool upgrade okf-cli

CLI overview

okf [OPTIONS] COMMAND [ARGS]...

Global options:

Commands

okf bundle

Convert a directory of plain markdown into an OKF bundle.

okf bundle <input-dir> [output-dir] [OPTIONS]

Arguments:

Options:

Examples:

okf bundle my-docs --default-type reference
okf bundle my-docs out --default-type reference --force
okf bundle my-docs --default-type reference --strict

Behavior:

• Skips index.md, log.md, README.md during input scanning.
• Reads .okfignore in the input root for exact bundle-relative paths to skip.
• Generates index.md in every directory containing concepts or subdirectories.
• Generates AGENTS.md at bundle root with navigation guidance (skipped with --strict).
• Warns about broken local .md links; --strict turns warnings into fatal errors.

okf validate

Check whether a directory conforms to the OKF specification.

okf validate <directory>

Reports errors and warnings per file. Exits non-zero on conformance failures.

okf list

List all concept IDs in a conformant OKF bundle.

okf list <directory>

Concept IDs are bundle-relative paths without the .md suffix, e.g. tables/orders.

okf read

Print a concept's full contents by concept ID.

okf read <directory> <concept-id>

Example:

okf read my-docs_knowledge_base tables/orders

Plain markdown input format

Best-quality input uses strict shape:

# Clear Concept Title

> One-sentence summary of this concept.

Body content with useful context, structure, examples, or schema.

Lenient fallback exists for imperfect files, but metadata quality may be lower.

Rules:

• First line: # Title
• Next block: > description (concise, factual)
• Directory name becomes the concept type: tables/orders.md → type tables
• Root-level files use --default-type, or the input directory name if omitted
• Do not add frontmatter to source files — okf bundle generates it
• Avoid creating index.md, log.md, or README.md as source concepts (reserved)

Typical workflow

# 1. Bundle
okf bundle my-notes --default-type reference --force

# 2. Validate
okf validate my-notes_knowledge_base

# 3. Explore
okf list my-notes_knowledge_base
okf read my-notes_knowledge_base some/concept

.okfignore

Place in the input root to exclude markdown files. Syntax:

# comments and blank lines allowed
private-notes.md
drafts/old-post.md

Entries are exact bundle-relative paths. No glob or negation support.

Reserved filenames

These files are never treated as concepts:

• index.md — generated directory listings
• log.md — changelog / activity log
• agents.md — agent navigation guidance (generated)
• README.md — skipped only during bundling input

Strict mode

Use --strict when you want:

• Broken local .md links to fail the bundle
• No AGENTS.md generated

Example:

okf bundle my-docs --default-type reference --strict

Tips

• Always run okf validate before consuming a bundle with list or read; those commands refuse non-conformant bundles.
• Use --force when regenerating bundles; output directories are not overwritten by default.
• Root-level markdown files get their type from the input directory name unless --default-type is set.
• Subdirectory markdown files get their type from the subdirectory name.