OKF CLI Guide — Build and Manage Knowledge Bundles from the Terminal

What Is the OKF CLI?

The OKF CLI isn't a single tool — it's the growing ecosystem of command-line utilities that let developers, AI engineers, and knowledge managers work with Open Knowledge Format (OKF) bundles directly from the terminal. These tools cover the full lifecycle: creating bundles from scratch, converting existing docs, validating conformance, linting for quality, searching across concepts, and publishing to discovery platforms like BundleDex.

Why Use the CLI Instead of a GUI?

Command-line tools offer several advantages for OKF workflows:

• Speed — Create and validate a bundle in seconds with a single command, no clicking through menus.
• Automation — Integrate OKF validation into CI/CD pipelines. Run okf validate on every commit to ensure your knowledge base stays conformant.
• Scriptability — Chain OKF CLI commands with other tools: scrape docs, convert to OKF, validate, and publish — all in one shell script.
• Agent-Native — AI coding agents (Claude Code, Codex, Cursor) are most comfortable running CLI commands. An okf cli tool is what your agent reaches for when it needs to manage knowledge.
• No Dependencies — Many OKF CLI tools are zero-dependency binaries (Rust, Go) that run anywhere without Node.js or Python runtimes.

The OKF CLI Ecosystem at a Glance

The ecosystem includes dedicated CLI tools (purpose-built for OKF), multi-purpose tools (OKF support as one feature), and developer tooling (linters, validators, schema checkers). Here are the major categories:

• Bundle Creation — okf-builder, okf-cli, OKFy
• Validation & Linting — openknowledge, okf-lint, okf-schema
• Search & Navigation — okq, factile, grepdown
• Memory & Context — crystalline, agentstate-lite, sill-ensoul
• Conversion & Import — OKFy, okf-convert, okf-kit, okfdump

Installing the OKF CLI

Installation varies by tool, but most follow standard package manager patterns. Below are the three most popular okf cli tools and how to get them running.

okf-cli — Convert Markdown to OKF Bundles

okf-cli is a purpose-built CLI that converts plain markdown files into OKF-conformant knowledge bundles. It handles frontmatter generation, directory structure, and cross-link validation. Ideal for turning existing markdown documentation into agent-ready bundles.

# Install via npm (recommended)
npm install -g okf-cli

# Or clone and build from source
git clone https://github.com/okf-cli/okf-cli.git
cd okf-cli && npm install && npm link

# Verify installation
okf-cli --version

OKFy — Docs to Bundles in One Command

OKFy (★59) is the most-starred dedicated OKF conversion tool. It transforms existing documentation directories, README files, and markdown collections into validated OKF bundles. It also functions as an MCP server, letting AI agents invoke OKF operations directly.

# Install via pip
pip install okfy

# Or via pipx for isolated install
pipx install okfy

# Convert a docs directory to OKF
okfy convert ./my-docs --output ./my-bundle

# Run as an MCP server
okfy serve

okf-builder — Guided Authoring for OKF v0.1

okf-builder (★4) provides an Agent Skills–compatible procedure for authoring, reading, and validating OKF bundles. It follows the OKF v0.1 specification and walks you through each required field step by step.

# Install via npm
npm install -g okf-builder

# Start an interactive bundle creation session
okf-builder init my-knowledge-bundle

# Follow the prompts to set title, description, concepts...

openknowledge — The Swiss Army Knife

openknowledge (★23) is a general-purpose CLI for managing OKF bundles. It handles creation, validation, linting, indexing, searching, and graph visualization — all from a single binary.

# Install via Homebrew (macOS)
brew install okf

# Or via Go
go install github.com/openknowledge/okf@latest

# Create a new bundle
okf init my-bundle

# Validate an existing bundle
okf validate ./my-bundle

Quick Comparison Table

Creating Your First OKF Bundle from the CLI

Let's walk through creating a complete OKF bundle using the command line. We'll use okf-builder for the guided approach and show the manual method too.

Method 1: Using okf-builder (Interactive)

# 1. Install okf-builder
npm install -g okf-builder

# 2. Initialize a new bundle
okf-builder init my-ai-knowledge

# 3. Follow the interactive prompts:
#    → Bundle title: "AI Agent Knowledge Base"
#    → Description: "Curated knowledge for coding AI agents"
#    → Add first concept: "prompt-engineering"
#    → Add concept description: "Techniques for writing effective AI prompts"
#    → Add more concepts? (y/n): y
#    → ... continue adding concepts ...

# 4. Builder generates the bundle structure:
#    my-ai-knowledge/
#    ├── index.md
#    ├── concepts/
#    │   ├── prompt-engineering.md
#    │   └── context-window.md
#    └── .okf/
#        └── okf.yaml

Method 2: Manual Creation (No Tools Required)

OKF bundles are just directories of markdown files. You can create one with any text editor and the terminal:

# 1. Create the bundle directory structure
mkdir -p my-bundle/concepts
mkdir -p my-bundle/.okf
cd my-bundle

# 2. Create the entrypoint (index.md)
cat > index.md << 'EOF'
---
title: "My First OKF Bundle"
description: "A collection of AI agent knowledge"
tags: [ai, agents, tutorial]
created: 2026-07-26
---
# My First OKF Bundle

Welcome to my knowledge bundle. Explore the concepts below.

## Concepts
- [Prompt Engineering](concepts/prompt-engineering.md) — Writing effective prompts
- [Context Windows](concepts/context-window.md) — Understanding token limits
EOF

# 3. Create your first concept document
cat > concepts/prompt-engineering.md << 'EOF'
---
title: "Prompt Engineering"
description: "Techniques for writing effective AI prompts"
tags: [ai, prompting, technique]
related: ["context-window"]
---
# Prompt Engineering

Prompt engineering is the practice of designing inputs
for AI models to produce optimal outputs.

## Key Techniques
- **Chain of Thought**: Ask the model to reason step by step
- **Few-Shot**: Provide examples in the prompt
- **Role Prompting**: Assign a persona to the model
EOF

# 4. Create the OKF manifest
cat > .okf/okf.yaml << 'EOF'
format: okf/v0.1
name: my-first-okf-bundle
entrypoint: index.md
EOF

# 5. Convert with okf-cli (optional, for auto-frontmatter)
okf-cli convert . --output ../my-bundle-okf

echo "Bundle created! Validate it next."

Method 3: Convert Existing Docs with OKFy

Already have documentation? OKFy converts it in one command:

# Convert a directory of markdown docs
okfy convert ./docs --output ./okf-bundle

# Convert a single README
okfy convert README.md --output ./okf-bundle

# Preview what will be created (dry run)
okfy convert ./docs --output ./okf-bundle --dry-run

Validating Bundles

Validation is critical — it ensures your bundle follows the OKF specification and can be reliably consumed by AI agents. The CLI ecosystem offers several validators, each with different strengths.

okf validate (openknowledge CLI)

The openknowledge CLI provides the most comprehensive validation:

# Basic validation
okf validate ./my-bundle

# Sample output:
# ✓ index.md found
# ✓ Frontmatter valid (title, description, tags present)
# ✓ concepts/ directory exists
# ✓ 3 concept files found
# ✓ All cross-links resolve
# ✗ Missing required field: 'created' in concepts/advanced.md
# ✗ Broken link: concepts/missing.md referenced from index.md
#
# Result: 5 passed, 2 failed
# Exit code: 1

okf-lint — CI/CD-Ready Validation

okf-lint (★6) is designed for CI/CD pipelines. It checks frontmatter, cross-links, generated indexes, and content freshness with a zero-dependency binary:

# Lint a single bundle
okf-lint ./my-bundle

# Lint with strict mode (warnings become errors)
okf-lint ./my-bundle --strict

# Lint and output JSON for CI tools
okf-lint ./my-bundle --format json

# Check for stale content (e.g., last modified > 90 days)
okf-lint ./my-bundle --stale-threshold 90

okf-schema — JSONSchema Validation

okf-schema (★6) validates OKF bundles against a formal JSON Schema, catching type errors and structural issues that other validators might miss:

# Validate against the OKF JSONSchema
okf-schema validate ./my-bundle

# Validate a specific concept file
okf-schema validate concepts/prompt-engineering.md --schema okf-v0.1

Manual Validation Checklist

Even without tools, you can validate your bundle manually. A conformant OKF bundle must have:

• index.md — Entrypoint with title, description, and tags in YAML frontmatter
• concepts/ — Directory containing at least one concept document
• YAML frontmatter — Every markdown file needs title and description fields
• Cross-links — All internal links must resolve to existing files
• .okf/okf.yaml — (Optional but recommended) Manifest declaring OKF version and entrypoint

Publishing to BundleDex

Once your bundle is created and validated, publish it to BundleDex so AI agents and developers can discover it. The CLI makes this straightforward.

Step 1: Push to GitHub

BundleDex indexes bundles from GitHub repositories. Push your bundle first:

cd my-bundle
git init
git add -A
git commit -m "Initial OKF bundle: AI Agent Knowledge Base"
git remote add origin https://github.com/your-username/my-bundle.git
git push -u origin main

Step 2: Submit to BundleDex

Visit the BundleDex submission page and enter your repository URL. BundleDex will:

1. Clone your repository
2. Validate OKF conformance
3. Extract metadata (title, description, tags, stars)
4. Add your bundle to the directory
5. Generate a dedicated bundle page (e.g., /bundles/my-bundle/)

Step 3: Automate with CI/CD (Optional)

Add validation to your GitHub Actions workflow so every push is checked:

# .github/workflows/okf-validate.yml
name: OKF Validation
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate OKF bundle
        run: |
          npx okf-lint . --strict
          echo "OKF bundle is valid!"

Top CLI Bundles in the OKF Ecosystem

Beyond the core tools covered above, the OKF ecosystem includes dozens of CLI-powered bundles. Here are the top-rated ones from the BundleDex directory:

Browse all 583 bundles on BundleDex to discover more CLI tools and knowledge bundles.

CI/CD Integration

One of the most powerful aspects of okf cli tools is their suitability for automated pipelines. Here are common integration patterns:

Pre-Commit Hooks

Catch OKF issues before they reach your repo:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: okf-lint
        name: Validate OKF bundle
        entry: okf-lint .
        language: system
        pass_filenames: false
        always_run: true

GitHub Actions

Run validation on every PR:

# .github/workflows/okf-check.yml
name: OKF Check
on:
  pull_request:
    paths:
      - 'concepts/**'
      - 'index.md'
      - '.okf/**'
jobs:
  okf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
      - run: go install github.com/okf-lint/okf-lint@latest
      - run: okf-lint . --strict --format json

Makefile Integration

Add OKF targets to your project Makefile:

# Makefile
.PHONY: okf-validate okf-create okf-publish

okf-validate:
	okf validate ./bundle

okf-create:
	okf-builder init ./bundle

okf-publish:
	okf validate ./bundle && \
	git add -A && \
	git commit -m "Update OKF bundle" && \
	git push
	@echo "Bundle updated! Submit at https://bundledex.net/submit"

Frequently Asked Questions About the OKF CLI

Related Guides

Continue exploring the OKF ecosystem with these related resources:

• OKF for Obsidian — Use OKF bundles in your Obsidian vault
• OKF for Claude Code — Load OKF bundles into Claude Code
• OKF vs Knowledge Graphs — When to use each approach
• How to Validate an OKF Bundle — Complete validation guide
• Best OKF Tools — Curated ranking of all OKF tools
• How to Create an OKF Bundle — Full step-by-step tutorial