Skip to content

CLI.md

Latest commit

 

History

History
230 lines (172 loc) · 7.95 KB

CLI.md

File metadata and controls

230 lines (172 loc) · 7.95 KB
Raw

OKF CLI & MCP Reference

The okf executable provides deterministic parsing, in-memory BM25 search, automated bookkeeping, and bundle validation for Open Knowledge Format (OKF) v0.2 corpora.

Global Usage

okf <command> [arguments] [flags]

General Flags

  • --json: Outputs machine-readable JSON instead of human-friendly terminal formatting.
  • --strict: Evaluates connectivity warnings (orphans, broken links) and provenance integrity (including superseded verifications verified.at < generated.at, missing actors, and v0.1 legacy syntax) as fatal gate errors.
  • --stale: Evaluates expired lifecycle dates (today >= stale_after) as fatal errors. By default, stale concepts are reported as lifecycle warnings without failing --strict, separating CI build integrity from temporal review cycles.
  • --drift: Detects discrepancies between concept frontmatter descriptions and parent index.md listings, and verifies that code_refs paths point to existing files/directories in the repository.

Commands Reference

1. validate

Audits an OKF bundle for structural conformance, graph health, provenance integrity, and lifecycle status.

okf validate [bundle-path] [--strict] [--stale] [--drift] [--json]
  • Arguments:
    • bundle-path (optional, default: ./knowledge or .): Path to the OKF bundle root directory.
  • Flags:
    • --strict: Fails the producer gate on broken links, orphans, superseded verifications, and schema discrepancies.
    • --stale: Fails the producer gate if any concept has reached or passed its stale_after date.
    • --drift: Checks whether concept listings in index files differ from concept descriptions, and verifies that code_refs point to valid source paths.
    • --json: Emits machine-readable JSON diagnostics.
  • Exit Codes:
    • 0: Valid & conformant (producer gate passed).
    • 1: Non-conformant or failed producer gate (--strict / --stale).
    • 2: File system or bundle loading error.

JSON Output Example:

{
  "bundle_path": "knowledge",
  "declared_version": "0.2",
  "concept_count": 7,
  "errors": [],
  "warnings": [],
  "broken_links": [],
  "orphans": [],
  "stale_count": 0,
  "is_conformant": true,
  "gate_passed": true
}

2. search

Searches concepts within a bundle using fast in-memory BM25 scoring across titles, descriptions, tags, IDs, and body text, or discovers concepts governing a specific file path via code_refs.

okf search [query] [bundle-path] [--for-path <file-or-dir>] [--limit <N>] [--json]
  • Arguments:
    • query (optional when --for-path is provided): Search terms or keywords.
    • bundle-path (optional, default: ./knowledge).
  • Flags:
    • --for-path <path>: Filters concepts governing a specific source file or directory via code_refs (exact match, directory prefix, standard glob, or recursive ** wildcard).
    • --limit <N> (default: 10): Maximum results to return.
    • --json: Outputs machine-readable JSON array of matching concepts with governance tiers and matched fields.

Governance Badges & Authority Ranking

Search results display an explicit governance badge indicating the concept's operational authority over code modifications:

  • [constraint]: Mandatory rule/guardrail (e.g. pure Go stdlib, zero external dependencies).
  • [hold]: Execution freeze / migration underway. Code under code_refs must NOT be edited without explicit human approval.
  • [context]: Informative domain background.

When querying by --for-path, results are deterministically prioritized: hold concepts appear first (stop-the-line), followed by constraint (rules), then context.

Terminal Output Example:

Found 2 matching concept(s) governing 'pkg/okf/types.go' in 'knowledge':

 1. [constraint] [22.00] architecture/governance-model (Decision)
    3-tier epistemic governance model (constraint, hold, context) and code-to-knowledge binding via code_refs.
    Matches: code_refs

 2. [context]    [0.31] architecture/layers (Architecture)
    Structural separation of concerns across the OKF specification, agent convention, skills, deterministic tooling, and knowledge corpus.
    Matches: title, description

3. show

Displays the full metadata, trust provenance, graph connections (inbound/outbound), and markdown body of a concept.

okf show <concept-id> [bundle-path] [--json] [--raw]
  • Arguments:
    • concept-id (required): Bundle-relative path without .md (e.g. architecture/layers).
  • Flags:
    • --raw: Emits the exact raw markdown file as stored on disk.
    • --json: Emits complete structured concept object.

4. create

Creates a new OKF concept file with valid frontmatter and automatically updates parent index.md and dated log.md.

okf create <concept-id> [bundle-path] \
  --type <Type> \
  --title "<Title>" \
  --desc "<One-sentence description>" \
  [--body "<Markdown body>"] \
  [--tags "tag1,tag2"] \
  [--actor "agent/<model>"] \
  [--no-log] \
  [--no-index] \
  [--json]
  • Flags:
    • --type: Normative OKF concept type (e.g. Decision, Architecture, Fact, Entity, Runbook).
    • --title: Human-readable concept title.
    • --desc: Exactly one concise sentence describing the concept.
    • --body: Markdown content following frontmatter.
    • --tags: Comma-separated list of tags.
    • --actor: Author string (default: agent/cli).
    • --no-log: Skips appending an entry to log.md.
    • --no-index: Skips updating the parent index.md listing.

5. update

Modifies an existing concept's metadata or body, updating timestamps and recording changes in log.md.

okf update <concept-id> [bundle-path] \
  [--title "<New Title>"] \
  [--desc "<Updated description>"] \
  [--body "<Updated body>"] \
  [--actor "agent/<model>"] \
  [--no-log] \
  [--no-index] \
  [--json]

6. relate

Adds a relative markdown link between two concepts, preventing link fragmentation and orphans.

okf relate <source-id> <target-id> [bundle-path] [--desc "<context>"] [--actor <actor>] [--json]
  • Example: 
    okf relate architecture/tooling architecture/layers knowledge --desc "Tooling implements the 5-layer architecture"

7. init

Initializes a bare OKF v0.2 bundle in a target directory with standard index.md (declaring okf_version: "0.2") and log.md.

okf init [directory-path]

8. bootstrap

Scaffolds a complete agent memory stack into an existing or new project.

okf bootstrap [target-dir] \
  [--name "<Project Name>"] \
  [--overwrite-agents-md] \
  [--no-skill] \
  [--no-agents-md] \
  [--no-makefile] \
  [--no-bundle]
  • Flags:
    • --name: Project name (defaults to directory name).
    • --overwrite-agents-md: Overwrite existing AGENTS.md instead of non-destructive smart-appending delimited section.
    • --no-skill: Skip installing .agents/skills/okf-memory/.
    • --no-agents-md: Skip creating/updating AGENTS.md.
    • --no-makefile: Skip installing convenience Makefile.
    • --no-bundle: Skip initializing knowledge/ scaffold.

9. mcp

Runs an embedded Model Context Protocol (MCP) server over standard I/O (stdio).

okf mcp [bundle-path]

Exposed MCP Tools

Tool Name Parameters Description
okf_search query (string, opt), for_path (string, opt), limit (int) Query memory corpus via BM25 ranking, or find concepts governing a file via code_refs.
okf_show concept_id (string) Fetch concept frontmatter, body, and graph links.
okf_create id, type, title, description, body, tags Create concept with automatic index & log bookkeeping.
okf_update id, title, description, body Update existing concept and record in log.md.
okf_relate source_id, target_id, description Link two concepts together.
okf_validate strict (bool), drift (bool) Verify bundle conformance.