Skip to content
OKForestOKForestOKForest

OKForest CLI

The OKForest CLI checks Open Knowledge Format (OKF) v0.2 trees, lists their metadata, and starts new ones. It is deterministic: no model calls and no network, and the same results on every machine. It is the same code that runs inside the OKForest service.

Terminal window
npx okforest validate .

It needs Node.js 22 or later. The source is at github.com/okforest/cli (Apache 2.0).

okforest validate [path]

Section titled “okforest validate [path]”

Checks a tree against the OKF v0.2 specification and OKForest’s conventions (see Rules), and prints each finding with its file and line.

Terminal window
okforest validate knowledge
okforest validate . --format json
  • Exits with 1 when there are errors, and 0 otherwise. Warnings and info never fail: a conformant bundle with, say, a broken link still passes, as the specification requires.
  • Exits with 2 on usage problems, such as a path that doesn’t exist.
  • --format json writes a versioned report (schemaVersion: 1) for CI and other tools. It is the same document the GitHub Action writes.

Diagram checks

Section titled “Diagram checks”

The D2 and Mermaid syntax checks use optional packages, about 200 MB together, so the CLI stays small without them. Install them alongside the CLI to turn the checks on:

Terminal window
npx -p okforest -p @d2lang/d2 -p mermaid okforest validate .

Without them, diagram blocks are reported as not checked (info). Some Mermaid diagram types (pie, gitGraph, and others) need a browser to parse and are also reported as not checked. The GitHub Action includes the diagram checks, with nothing to install.

okforest inventory [path]

Section titled “okforest inventory [path]”

Lists every type, tag, and frontmatter key in use, with counts, status and trust totals, and likely near-duplicates (e-commerce and ecommerce, Policy and Policies). Use it to settle on one vocabulary before a tree grows.

Terminal window
okforest inventory . --format json

okforest init [path] --template company

Section titled “okforest init [path] --template company”

Starts a new tree:

  • a root index.md declaring okf_version: "0.2", and log.md;
  • .okforest/tree.yaml naming the Owner (--owner, defaulting to your Git email);
  • draft starter concepts;
  • .github/workflows/okforest-validate.yml, which runs the OKForest Validate action on every pull request.
Terminal window
npx okforest init acme-okf --template company --owner jane@acme.example

What counts as a concept

Section titled “What counts as a concept”

Every .md file is a concept except index.md and log.md (reserved by OKF), files under hidden directories (.github/, .okforest/), and these repository files at the tree root: README.md, LICENSE.md, CONTRIBUTING.md, CHANGELOG.md, SECURITY.md, and CODE_OF_CONDUCT.md. Skip others with ignore: globs in .okforest/tree.yaml:

ignore:
  - FOLLOWUPS.md
  - drafts/

As a library

Section titled “As a library”

The CLI is built on two packages you can use directly, in Node, browsers, and Workers:

  • @okforest/okf reads a tree into a model: concepts, links, backlinks, trust tiers, staleness, and the metadata inventory.
  • @okforest/validate runs the rules and returns structured findings.