openknowledge

README

Open Knowledge

Open-source runtime for self-hosted, self-maintaining knowledge bases.

Open Knowledge creates Git-native project knowledge bases in plain Markdown and can deploy them as isolated public and private runtimes. The public role serves an immutable filtered wiki, search, and optional read-only HTTP MCP. The private runtime splits GitHub publication from model execution: a credentialed publisher follows production and promotes artifacts, while isolated Codex, Claude Code, or OpenCode workers run scheduled jobs and propose draft pull requests through Git bundles without receiving GitHub credentials.

🌐 Website | 📖 README | 🗂️ Repository wiki | 📝 Changelog | 📐 OKF spec | ⚖️ License

Contents

• Why Open Knowledge
• At A Glance
• Start Here
• Command Map
• Common Workflows
• How It Works
• Command Reference
• Validation
• Development
• License And Attribution

Why Open Knowledge

Open Knowledge is a small tooling stack around Markdown knowledge bases. It is useful when you want an LLM wiki, LLM Wikipedia-style project memory, or Karpathy-style project wiki that stays inspectable with normal shell tools.

It gives you:

• plain-file knowledge bases that agents and humans can both edit
• source-to-wiki prompts for turning repositories, local folders, or websites into OKF Markdown bundles
• deterministic validation, listing, search, MCP, AST, JSON, graph, tar, and HTML views of the same bundle
• local registry aliases so agents can address knowledge bases by stable names
• a local viewer and static publisher with connect manifests and portable bundle archives
• a steered local agent interface for Codex, Claude Code, and OpenCode, plus optional experimental Markdown-authored jobs for scheduled maintenance
• a Docker runtime with public serve, credentialed private publisher, and model-capable private worker roles separated by artifacts and Git bundles
• openknowledge deploy railway for secret-scoped, idempotent provisioning with a Railway URL, a user-owned custom domain, or no public endpoint

Open Knowledge implements Google's Open Knowledge Format v0.1 specification, a Markdown and YAML-frontmatter standard designed to stay easy to inspect, diff, validate, and maintain.

At A Glance

	Capability	What it gives you
🤖	Agent setup	openknowledge setup [wiki] creates or refreshes a wiki through Codex, Claude Code, or OpenCode; add --from <source> to ground it in existing material.
📝	Plain Markdown	Knowledge stays in Git-friendly files that humans can read and agents can patch.
🔍	Retrieval	search builds budget-bounded Markdown context by default, while get, list, and view support exact reads, structure, and browsing.
🔌	MCP integration	mcp serves exact resources, source-grounded search, and validation to compatible LLM hosts over read-only stdio.
📦	Portable publishing	HTML exports include llms.txt, openknowledge.json, and a bundle archive so published wikis can be connected again.
⚙	Deterministic checks	validate, ast, JSON, graph, and experimental agent job commands provide structured views that automation can trust.
🛡	Isolated runtime	runtime serve consumes only public generations; publisher and per-harness jobs roles keep GitHub and model credentials in different containers and state volumes.
🚀	Five-minute deploy	deploy railway validates publication, provisions isolated services and volumes, and never purchases or registers a domain.

flowchart LR
  Source["Repository, docs, website, or local folder"] --> Setup["openknowledge setup --from"]
  Setup --> Agent["Local coding agent"]
  Agent --> Wiki["OKF Markdown wiki"]
  Wiki --> Use["get / search / list / view / mcp"]
  Wiki --> Check["validate / ast"]
  Wiki --> Publish["export html / json / graph / tar"]
  Publish --> Connect["connect remote or archive"]

Start Here

Create a wiki from your project

From the project repository that should own the wiki, install the CLI and run the canonical setup command:

curl -fsSL https://openknowledge.sh/install | bash
openknowledge setup Wiki --from .

setup is the controller: it launches Codex by default, asks the agent to inspect the current repository, creates a source-grounded Wiki, validates the result, and installs project integration. When it finishes, open the result with openknowledge view Wiki.

Start a guided wiki without a source

Omit --from when you want the launched agent to interview you about a new or more open-ended knowledge base:

openknowledge setup Wiki

Preselect maintenance rules when you already know the wiki shape:

openknowledge setup Wiki --rules docs,changelog

Use another source or agent runtime

Pass another repository, folder, or website to --from when the current project is not the source:

openknowledge setup Wiki --from https://github.com/openknowledge-sh/openknowledge --type understanding
openknowledge setup Wiki --from . --runtime claude

The command launches a local agent to inspect the source, create or update an OKF bundle, preserve source provenance, validate the result, and install the repository integration. Select Claude Code or OpenCode with --runtime claude or --runtime opencode. For print-only instructions, use the advanced prompt namespace.

Install manually

curl -fsSL https://openknowledge.sh/install | bash
# Or: npm install -g @openknowledge-sh/openknowledge

Both installers expose openknowledge and the shorter okn alias. For example, okn validate Wiki is equivalent to openknowledge validate Wiki.

Both installers verify the release checksum before publishing the binary. The npm wrapper also bounds downloads and decompression, limits HTTPS redirects, and accepts only the exact regular openknowledge archive member.

Published platform archives also carry GitHub/Sigstore build provenance. After downloading an archive, verify its digest and signing repository identity with gh attestation verify <archive> -R openknowledge-sh/openknowledge and inspect the recorded workflow and commit.

For an advanced, deterministic scaffold that does not launch an agent or install Git integration, create and inspect a local bundle manually:

openknowledge scaffold ./project-memory
openknowledge validate ./project-memory
openknowledge list ./project-memory
openknowledge search ./project-memory "validation workflow"
openknowledge view ./project-memory

Command Map

Layer	Commands	Use them for
Agent setup	setup, agent, insights, jobs	Create, integrate, and maintain a wiki through local agents and repeatable jobs.
Advanced portable tools	scaffold, prompt setup, prompt from, prompt rules, prompt review	Scaffold without an agent or print portable instructions for an external agent host.
Authoring and format hygiene	scaffold, spec, validate, list, ast	Create bundles, inspect structure, parse Markdown, and enforce portable OKF rules.
Experimental local agent automation	agent, jobs	Run direct local agent sessions; validate, schedule, start, observe, stop, and inspect local agent jobs in isolated Git worktrees.
Self-hosted runtime	runtime, deploy	Plan, build, serve, privately reconcile, and provision immutable knowledge-base generations.
Registry and lifecycle	connect, disconnect, registry, export tar	Give local, published, archive, or Git knowledge bases stable names and package portable source archives.
Use and navigation	get, search, list, view, mcp	Read exact Markdown files, inspect bundle trees, build source-preserving context, inspect ranked matches, browse locally, and connect MCP-compatible LLM hosts.
Views and publishing	export json, export graph, export graph --type search, export html, export html --plain	Export normalized models, source graphs, retrieval graphs, static viewers, and plain semantic HTML.

Common Workflows

Create a deterministic scaffold (advanced)

openknowledge scaffold ./project-memory
openknowledge scaffold --no-agents --no-setup ./source-wiki
openknowledge scaffold --name "Accessibility Review" --bundle-name accessibility --bundle-tag accessibility ./accessibility

Connect and navigate

openknowledge connect ./project-memory --as personal
openknowledge get personal --info
openknowledge get personal
openknowledge search personal "validation workflow"
openknowledge search personal "validation workflow" --budget 1200
openknowledge search personal "validation workflow" --matches
openknowledge mcp personal
openknowledge registry where personal
openknowledge view personal
openknowledge disconnect personal

Validate and inspect

openknowledge validate ./project-memory
openknowledge validate --format json ./project-memory
openknowledge list --depth 2 ./project-memory
openknowledge ast ./project-memory

Publish or export

openknowledge export html --out ./project-site ./project-memory
openknowledge export html --plain --out ./project-plain-site ./project-memory
openknowledge export json ./project-memory
openknowledge export graph ./project-memory
openknowledge export graph --type search ./project-memory
openknowledge export tar --out ./project-memory.tar.gz ./project-memory

Run the isolated Docker runtime

Copy and edit deploy/runtime/runtime.toml, create the GitHub App secret plus the model-key files for the harness profiles you want, then run, for example:

docker compose -f deploy/runtime/docker-compose.yml --profile codex up --build
# Add --profile claude and/or --profile opencode when enabled.

The serve container mounts the artifact volume read-only and receives no Git, model, or GitHub credentials. The ingress-free publisher alone receives the GitHub App key and artifact write access. Each ingress-free harness worker gets only its model/provider key and a separate persistent checkout. The roles exchange only bounded Git bundles and sanitized request records. See the runtime command reference before using the example in production.

Deploy the runtime to Railway

# Review the exact resources and credential names; no secrets are read or shown.
openknowledge deploy railway Wiki --dry-run

# Provision serve, publisher, inferred harness workers, volumes, and a Railway URL.
openknowledge deploy railway Wiki --yes

Use --domain docs.example.com only for a hostname you already own; the result prints Railway's required CNAME/TXT records. Use --no-public-endpoint for a private deployment or --without-worker when scheduled agents are not needed. Open Knowledge infers codex, claude, and opencode workers from enabled job files; no enabled jobs means no worker, and --runtimes can override that selection. It never searches for, buys, or registers domains. Railway CLI v5+ authentication, a GitHub token (or authenticated gh), and the selected harness keys (CODEX_API_KEY, ANTHROPIC_API_KEY, and/or OPENCODE_API_KEY) are required for the full mutating deployment. See the deploy command reference.

Keep .openknowledge/deployments/railway.json after the first run; it contains no secrets and lets later runs reuse the same resources safely. The command returns after Railway accepts the redeploy. Verify the generated endpoint at /_openknowledge/readyz once the publisher has produced its first snapshot.

How It Works

Agent setup

openknowledge setup [wiki] runs the complete onboarding workflow through a supported local agent harness. The agent inspects the workspace, asks only for missing setup decisions, chooses maintenance rules such as docs, changelog, decisions, research, bugs, schemas, summary, or agents, creates the bundle, and validates the result. The CLI then validates the bundle and installs project integration.

openknowledge prompt rules prints Markdown instructions for agents that maintain an existing wiki. It does not edit files. Use openknowledge prompt rules apply when you want the CLI to write an idempotent managed block into an agent instruction file such as AGENTS.md, CLAUDE.md, or Cursor project rules.

openknowledge prompt review rules prints an advisory AI review prompt for checking whether selected maintenance rules appear to have been followed. It does not call a model, edit files, or affect validation status.

Source-to-wiki prompts

openknowledge prompt from <source> --out <folder> prints a source-to-wiki agent prompt. Use it with a GitHub repository, local path, or website entrypoint when you want a local agent to create or refresh an OKF bundle from existing material.

--type understanding is the default DeepWiki-style recipe for overview, architecture, structure, workflows, entrypoints, diagrams, glossary, and citations. --type custom asks the agent to interview for the wiki goal; pass --about "<goal>" to make that non-interactive. --depth <n> is a crawl or traversal hint for sources that need one.

Bundle lifecycle

openknowledge scaffold creates a minimal local bundle with a root index, update log, and pinned copy of the current spec. By default it also includes a setup handoff and starter agent guidance. Pass --no-agents or --no-setup when those optional handoff files are not useful for the workflow.

After creation, humans and agents edit normal Markdown files. openknowledge validate checks the bundle, openknowledge list prints the bundle tree, openknowledge get prints exact files or declared entrypoints, and openknowledge search uses deterministic BM25 ranking to build source-preserving Markdown context under a token budget. One-hop local links and backlinks are included by default when they fit; --matches exposes the underlying ranked snippets and scores. Both search shapes bind results to the indexed Markdown revision and expose content-addressed section locators, so an integration can detect stale evidence after a knowledge-base refresh. openknowledge search --all <query> searches the current local registry snapshot, combines per-bundle ranks with deterministic reciprocal-rank fusion, and applies one global source limit and context budget without refreshing managed remotes.

Registry and viewer

openknowledge connect stores stable names for local paths, published manifests, tar archives, and Git sources. A key is only an alias: path-based commands still work, and agents can use openknowledge registry where <key> to resolve the real folder before using normal filesystem tools such as rg. Remote Git materialization is non-interactive, has a two-minute process budget, and caps captured subprocess diagnostics at 256 KiB, so unattended agent runs cannot hang on credentials or consume unbounded memory through Git output. Each clone/fetch/checkout step is followed by a staging-tree limit check: 100,000 entries, 256 MiB per file, and 2 GiB total. Over-limit generations are removed without validation, content hashing, registry mutation, or publication. Remote source URLs are persisted as provenance and therefore reject embedded userinfo, passwords, fragments, and known credential query parameters before any network or filesystem I/O. Git authentication must use SSH keys or a credential helper; HTTP sources must be reachable without URL-embedded secrets.

openknowledge view starts a registry-backed local viewer. openknowledge view <path-or-name> opens one knowledge base directly. The viewer serves registered knowledge bases under stable local paths such as /personal/; those path aliases do not require DNS or /etc/hosts changes. While it is running, registry mode picks up connections, disconnections, refresh generations, and access changes without a restart; invalid registry state fails requests instead of preserving stale routes.

Publishing

openknowledge export html writes a static viewer app bundle by default, including searchable Markdown tables, llms.txt, an openknowledge.json connect manifest, and an assets/openknowledge-bundle.tar.gz source archive. Published exports can be connected later:

openknowledge connect https://openknowledge.sh/wiki/

openknowledge export html --plain writes unstyled semantic HTML. openknowledge export json writes a normalized bundle model. openknowledge export graph writes an AST-backed source graph. openknowledge export graph --type search writes a retrieval-oriented chunk graph.

Go API

Go applications can embed the same read-only core without spawning the CLI:

import "github.com/openknowledge-sh/openknowledge/packages/cli/okf"

report, err := okf.ValidateWithVersion("./Wiki", "0.1")
packet, err := okf.ResolveContextWithVersion("./Wiki", "0.1", okf.ContextOptions{
    Query: "release workflow", Budget: 1200, Limit: 8,
})
entries, err := okf.RegistryEntries()
root, err := okf.ResolveKnowledgeRoot("team-docs")

The public package covers parsing, validation, listing, deterministic search, source context, graphs, metadata, manifests, spec discovery, and strict read-only registry inventory, key/path resolution, and authoring-capability checks. Registry/network mutation, extraction, publishing, and viewer lifecycle remain explicit CLI workflows. See Go API for the full boundary and versioning model.

Static viewer exports can inject trusted deployment-owned head HTML with --head-file, --head-html, repeatable --script-src, or matching OPENKNOWLEDGE_HEAD_* and OPENKNOWLEDGE_SCRIPT_SRC environment variables. Bundle-local openknowledge.toml can also configure HTML theme, site, and source-link metadata:

[html.theme]
name = "landing"
stylesheet = "assets/wiki-theme.css"

[html.site]
base_url = "https://openknowledge.sh/wiki/"

[html.source]
github_base = "https://github.com/openknowledge-sh/openknowledge/blob/main"
entry = "Wiki"

The file uses one strict typed TOML contract across HTML, validation, and rules; unknown sections/fields and wrong value types fail closed. See the configuration reference.

Experimental Agent And Jobs

openknowledge agent is the human-facing path. It starts Codex by default and supports Claude Code or OpenCode with --runtime. It accepts an optional initial prompt or runs a non-interactive task with agent exec. A versioned Open Knowledge steering contract is prepended by default. Managed onboarding and source generation use openknowledge setup; agent doctor probes installed harnesses without starting a model. Direct filesystem editing is the default, so local sessions do not create a branch, commit, or pull request. Add --isolate to create and retain a dedicated branch and Git worktree at the repository's current HEAD. Open Knowledge probes harness executables before creating the worktree. Overrides are OPENKNOWLEDGE_CODEX, OPENKNOWLEDGE_CLAUDE, and OPENKNOWLEDGE_OPENCODE; Codex discovery also skips broken PATH wrappers and checks supported macOS app bundles.

openknowledge agent integrate --global installs only a discovery skill for Codex, Claude Code, and OpenCode. openknowledge agent integrate Wiki explicitly connects the current repository to Wiki, installs project-scoped skills and native project hooks, and records the relationship in .openknowledge/integration.toml. Direct harness sessions and openknowledge agent then write private, uncommitted Markdown observations to Wiki/insights/. The bounded observer analyzes available session messages, tool events, failures, retries, validation events, and Git changes, but commits neither raw transcripts nor credentials.

openknowledge insights is the small shared interface for people, agents, and automation. Capture a durable knowledge gap deterministically with openknowledge insights create "<summary>"; repeat --target and --evidence when the likely knowledge location or source evidence is known. List pending items with openknowledge insights, execute one with openknowledge insights run <insight>, process all with run --all, or add --isolate for a retained local branch and worktree. create never invokes a model; run performs fresh agent research, leaves an ordinary uncommitted Git diff, and validates the result before marking an insight resolved. Insights contain only a sanitized outcome, evidence, and likely targets—never a patch or base commit. For scheduled maintenance, generate .openknowledge/jobs/insights.md with openknowledge jobs new insights --out .openknowledge/jobs/insights.md. Insights always declare okf_publish: false and are absent from every public artifact.

openknowledge jobs is experimental. It runs deterministic automation around local agent CLIs, but the job schema and scheduler behavior may still change before this command is treated as stable. Jobs are Markdown files with nested frontmatter for schedule, closed agent runtime/model, workspace, sandbox, verification, and output settings. The Markdown body is the agent prompt. Jobs that share a concurrency.key use an owner-private cross-process lock; the supported skip policy records a skipped invocation without creating a second worktree when that key is already running.

Use openknowledge jobs new to list shipped templates, openknowledge jobs new <template> --out <file> to write one, openknowledge jobs validate to check job specs, and openknowledge jobs run <job.md> --dry-run to print the resolved run plan. Run openknowledge jobs run <job.md> to create a Git worktree and run the selected Codex, Claude Code, or OpenCode adapter. Use openknowledge jobs start <job.md> for a detached run, openknowledge jobs status for schedules plus active/latest runs, and openknowledge jobs runs for repository history. Live runs can be cancelled with openknowledge jobs stop <run-id> or force-terminated with openknowledge jobs kill <run-id>; both address the owning supervisor rather than trusting a stored PID. Scheduled jobs still require a running openknowledge jobs daemon process. openknowledge jobs list --json exposes a sorted, versioned discovery inventory with structured schedules, executor types, and concurrency keys, without serializing prompt bodies or environment values. openknowledge jobs validate --json emits a versioned report on stdout for both valid and invalid specs; validation findings remain structured data while exit status 1 still marks an invalid job. Job dry-run plans, persisted plan.json and run.json, and management command JSON outputs use the single current schemaVersion: "1" contract. Cancellation and kill outcomes are explicit in that run-record schema.

Command Reference

Run openknowledge <command> --help for command-specific flags and examples. Nested job commands also support openknowledge jobs <subcommand> --help.

Command	Purpose
openknowledge --help	Print command usage, summaries, and examples.
openknowledge --error-format json <command> ...	Emit operational and usage failures as a versioned JSON envelope on stderr.
openknowledge setup [wiki]	Run agent-guided setup, validate the result, and install project integration.
openknowledge setup [wiki] --from <source>	Create or refresh a wiki from a source URL or path.
openknowledge prompt setup [--rules <rules>]	Print the portable setup prompt without running an agent.
openknowledge prompt from <source> --out <folder>	Print the portable source-to-wiki prompt.
openknowledge prompt rules --list	List available built-in and wiki-local maintenance rules.
openknowledge prompt rules <rules> --path <path>	Print ready-to-paste maintenance rules.
openknowledge prompt rules apply <rules> --path <path> --file <file>	Write or replace a managed rules block in an agent instruction file.
openknowledge prompt review rules [path]	Print an advisory AI rule-review prompt.
openknowledge agent ["<initial prompt>"]	Experimental: start a steered interactive Codex session, or select Claude Code/OpenCode with --runtime.
openknowledge agent exec "<prompt>"	Experimental: run one non-interactive task through the selected harness.
openknowledge agent exec --isolate "<prompt>"	Experimental: run one task in a retained branch and worktree.
openknowledge agent doctor [--runtime <runtime>]	Experimental: probe supported harness installations.
openknowledge agent integrate --global	Install discovery-only user skills without hooks or observation.
openknowledge agent integrate <wiki>	Connect a repository to a knowledge base and install project skills/hooks.
openknowledge insights create "<summary>" [--target <path>] [--evidence <text>]	Deterministically capture a private, evidence-only knowledge insight.
openknowledge insights [list] [wiki]	List pending private Markdown insights oldest first; without a path, use the project integration.
openknowledge insights run <insight>	Research and implement one insight locally, validate it, and leave an uncommitted diff.
openknowledge insights run --all [--isolate]	Process all pending insights directly or in a retained local branch/worktree.
openknowledge insights dismiss <insight>	Mark a pending insight dismissed.
openknowledge jobs new	Experimental: list built-in local agent job templates.
openknowledge jobs new <template> --out <file>	Experimental: write a built-in agent job template to a Markdown file.
openknowledge jobs new --reference	Experimental: print the supported agent-job schema.
openknowledge jobs list [path]	Experimental: list Markdown agent job specs.
openknowledge jobs list [path] --json	Experimental: print the versioned agent discovery inventory.
openknowledge jobs status [jobs-dir]	Experimental: show schedules, next eligible slots, and active/latest runs.
openknowledge jobs runs [repo]	Experimental: list current and historical runs, newest first.
openknowledge jobs start <job.md>	Experimental: start one job in a detached local supervisor.
openknowledge jobs stop <run-id>	Experimental: request cancellation of a live supervised run.
openknowledge jobs kill <run-id>	Experimental: force-cancel a live run's command process tree.
openknowledge jobs validate <job-or-dir>	Experimental: parse and schema-check agent job specs.
openknowledge jobs validate <job-or-dir> --json	Experimental: print the versioned validation report, including failures.
openknowledge jobs run <job.md> --dry-run	Experimental: print the resolved deterministic run plan.
openknowledge jobs run <job.md>	Experimental: create a Git worktree and run one local agent job.
openknowledge jobs daemon [jobs-dir] --once [--runtime <runtime>]	Experimental: attempt due jobs, optionally restricted to one harness.
openknowledge runtime plan --config runtime.toml	Strictly validate and print the normalized self-hosted runtime plan.
openknowledge runtime build --config runtime.toml	Build and promote filtered immutable public generations.
openknowledge runtime serve --config runtime.toml	Serve verified static wiki, search, and optional read-only HTTP MCP snapshots.
openknowledge runtime worker --role publisher --config runtime.toml	Fetch production, promote artifacts, validate agent bundles, and publish draft PR output with GitHub credentials.
openknowledge runtime worker --role jobs --runtime <runtime> --config runtime.toml	Run one harness's scheduled jobs with its model credential and export proposed Git branches without GitHub or artifact access.
openknowledge deploy railway [path] --dry-run	Validate publication and print the secret-free Railway resource plan.
openknowledge deploy railway [path] --yes	Idempotently provision isolated runtime services, credentials, volumes, and the selected public endpoint mode.
openknowledge scaffold [folder]	Scaffold a local Open Knowledge bundle.
openknowledge scaffold --no-agents --no-setup [folder]	Scaffold without starter agent rules or a setup handoff.
openknowledge connect <source>	Connect a local path, registry key, manifest URL, tar archive URL, or Git URL.
openknowledge connect <source> --as <key>	Connect a bundle with an explicit key.
`openknowledge connect --git-ref <branch	tag
openknowledge disconnect <key-or-path>	Remove a connection while keeping files.
openknowledge disconnect <key-or-path> --delete-files	Delete files only for CLI-managed remote caches.
openknowledge get <name-or-path>	Print an exact local Markdown file, default entrypoint, or root index.md.
openknowledge get <name-or-path> <entry-or-file>	Print a named bundle entrypoint or bundle-relative Markdown file.
openknowledge get <name-or-path> --info	Print bundle and selected-file metadata.
openknowledge search <name-or-path> <query>	Build source-preserving Markdown context with related authored links.
openknowledge search <name-or-path> <query> --budget <tokens>	Bound the approximate context size.
openknowledge search <name-or-path> <query> --no-expand	Include only direct lexical matches.
openknowledge search <name-or-path> <query> --matches	Inspect ranked snippets, scores, and relations.
openknowledge search <name-or-path> <query> --format json	Print structured context JSON.
openknowledge search --all <query>	Fuse source context across every registered knowledge base under one global budget.
openknowledge search --all <query> --matches --format json	Inspect the versioned federated rank-fusion contract.
openknowledge mcp [name-or-path]	Serve one bundle as read-only MCP resources plus search and validation tools over stdio.
openknowledge mcp --spec <version> [name-or-path]	Select the OKF spec used by MCP search, validation, and resource discovery.
openknowledge ast [key-or-path]	Print parsed OKF AST JSON.
openknowledge ast --out <file> [key-or-path]	Write parsed OKF AST JSON to a file.
openknowledge registry refresh <key-or-path> [--force]	Atomically fetch and switch a managed remote connection to a newly validated cache generation.
openknowledge registry list	List connected knowledge base paths.
openknowledge registry list --json	Discover sorted connections, access capabilities, managed state, and source provenance through versioned JSON.
openknowledge registry status [key-or-path] --json	Check local bundle, cache, Git, and provenance integrity without contacting remotes.
openknowledge registry where <name-or-path>	Print the absolute path for a registry name or path.
openknowledge view [path]	Start the registry or knowledge base Markdown viewer.
openknowledge view --allow-network --host <host> [path]	Explicitly bind beyond loopback with token authentication on every route.
openknowledge view --name <alias-name> [path]	Start a direct viewer with a stable local alias path.
openknowledge export html --out <folder> [key-or-path]	Write a static viewer app bundle plus llms.txt, connect manifest, and tar archive.
openknowledge export html --plain --out <folder> [key-or-path]	Write unstyled semantic HTML files.
openknowledge export json [key-or-path]	Print normalized Markdown-document bundle JSON.
openknowledge export json --out <file> [key-or-path]	Write normalized Markdown-document bundle JSON to a file.
openknowledge export tar --out <file> [key-or-path]	Write a portable bundle tar.gz archive.
openknowledge export graph [key-or-path]	Print AST-backed source graph JSON.
openknowledge export graph --out <file> [key-or-path]	Write AST-backed source graph JSON to a file.
openknowledge export graph --type search [key-or-path]	Print derivative search graph JSON with H1-H3 chunk nodes.
openknowledge spec latest	Print the latest embedded OKF spec.
openknowledge spec 0.1	Print a specific embedded spec version.
openknowledge validate [key-or-path]	Validate a bundle against the latest spec.
openknowledge validate --format json [key-or-path]	Print a machine-readable validation report.
openknowledge validate --rule <rule=off|warn|error> [key-or-path]	Override one validation rule severity for the run.
openknowledge list [key-or-path]	Print a bundle tree with inline validation issues.
openknowledge list --depth <n> [key-or-path]	Limit the displayed tree depth.
openknowledge list --json [key-or-path]	Print machine-readable inventory output.
openknowledge version	Print the CLI version.

Validation

openknowledge validate enforces the OKF v0.1 rules that matter for a portable bundle:

• every non-reserved Markdown file has top-level YAML frontmatter
• every concept frontmatter has a non-empty type
• Markdown files are valid UTF-8 before parsing
• YAML frontmatter parses cleanly; non-blocking formatting issues are warnings
• Markdown bodies avoid malformed links, code spans, tables, and fences
• index.md and log.md are reserved files, not concept documents
• root index.md may declare okf_version: "0.1" and optional okf_bundle_* metadata; unknown root frontmatter keys are tolerated
• public artifacts require explicit [publish] enabled = true; the default is deny
• any page may use boolean okf_publish: false as a hard all-artifact deny and okf_targets booleans for viewer, search, MCP, llms.txt, and sitemap routing
• log.md ## headings use YYYY-MM-DD
• local Markdown links resolve inside the bundle, reported as warnings
• symbolic links below the bundle root are rejected so reads and exports cannot escape the real filesystem boundary
• custom rule files under configured [rules].paths have canonical IDs, summaries, and instruction bullets

It does not fail on optional fields, unknown concept types, unknown frontmatter keys, broken local links, non-blocking Markdown syntax warnings, or missing index files.

For CI and editor integrations, openknowledge validate --format json emits a machine-readable report with summary counts, checks, active severity policy, and combined or separate issue arrays. Bundle-local openknowledge.toml can configure lint severities under [validation.rules], and repeatable --rule flags can override them per run.

Machine-readable agent plans, records, and management results, AST, normalized bundle, graph, list, registry list/status, search, and validation outputs declare schemaVersion: "1". Draft 2020-12 schemas live in packages/cli/schemas/v1/; specVersion separately identifies the selected Open Knowledge Format version. Tests compile the schemas and validate golden plus representative non-empty outputs, while the website publishes them at https://openknowledge.sh/schemas/cli/v1/<name>.schema.json. Automation that also needs structured command failures can place the global --error-format json option before the command. Failures that wrote diagnostic text are emitted as one cli-error.schema.json document on stderr, while successful output and existing machine results stay on stdout unchanged. In particular, an invalid validation report keeps its nonzero status and complete JSON stdout document without adding a second error envelope. The separately versioned portable openknowledge.json manifest contract is published at https://openknowledge.sh/schemas/cli/manifest/v1/bundle.schema.json; remote connect rejects unknown or duplicate fields and trailing JSON. Versioned local registry and managed-cache provenance schemas are published under https://openknowledge.sh/schemas/cli/storage/v1/. Persistence readers reject unknown or duplicate fields, trailing JSON, unsupported versions, and invalid registry identity/path/access invariants before mutation.

Development

pnpm test:cli
pnpm test:install
pnpm test:npm-install
pnpm test:web
pnpm check:versions
pnpm check:workflow-pins
pnpm check:workflow-secret-scope
pnpm check:workflow-permissions
pnpm check:security-config
pnpm check:container-runtime
pnpm build:cli
pnpm build:web
pnpm dev:web

This repository keeps CLI documentation in the colocated Wiki. When a command, flag, exporter, validation rule, viewer behavior, setup flow, or release-facing package behavior changes, update the relevant wiki page and CLI changelog memory with the source-backed behavior.

License And Attribution

Open Knowledge is licensed under Apache-2.0.

The embedded OKF spec copy is Apache-2.0 material from GoogleCloudPlatform/knowledge-catalog. See THIRD_PARTY_NOTICES.md and packages/cli/internal/okf/assets/specs/README.md for attribution and license handling.