Skip to content
KnowFlow logoKnowFlow

Commands

KnowFlow is a single knowflow CLI. Commands search upward from the current directory for the nearest .knowflowrc to locate the project root, so they also work from inside project subdirectories.

A real session

Section titled “A real session”
Terminal window
$ knowflow init my-wiki && cd my-wiki
✅ 已创建 /path/to/my-wiki/.knowflowrc
✅ KnowFlow 项目已初始化: /path/to/my-wiki


$ knowflow ingest "Karpathy's LLM Wiki essay: an agent curates saved links into durable, linked wiki pages." --source text
🔗 开始采集素材...
✅ 采集完成！                       # → raw/web/<timestamp>-note.md


$ knowflow graph --no-open
🕸️  构建知识图谱...
✅ 图谱已生成: /path/to/my-wiki/graph/graph.html


$ knowflow health
🏥 Wiki 健康检查...
✗ wiki/concepts/linked-knowledge.md → [[sources/missing]] (not found)
⚠️  发现一些问题，建议修复（knowflow fix）   # exit code 1


$ knowflow fix --dry-run
🔧 自动修复 Wiki 问题...
[dry-run] 会创建缺失页面: wiki/sources/missing.md
Command What it does
init Create a standalone project
ingest Capture a URL or text into raw/
compose List raw material not yet synthesized into wiki pages
check Run the eight-condition conformance gate over the four page types
status Show project statistics, index states, and the pending-review list
health Check broken links, small files, and orphans
fix Repair the issues health finds (never touches pending pages)
graph Build the interactive knowledge graph (pending pages are skipped)
tags Rebuild tag hub pages
index Build / inspect the vector index (optional; pending pages are skipped)
query Hybrid semantic search (optional)
ask Answer questions from Wiki context with citations (optional)

init

Section titled “init”
Terminal window
knowflow init [directory]

Creates a standalone project (defaults to the current directory):

  • .knowflowrc — JSON configuration, only written if it does not exist yet
  • wiki/ with sources/, entities/, concepts/, comparisons/ subdirectories and a starter index.md
  • raw/ with web/, twitter/, xiaohongshu/, wechat/ subdirectories
  • graph/ output directory
  • templates/ — the editable Markdown page templates, copied from the package

Running init again preserves existing configuration, the starter index, and customized templates.

ingest

Section titled “ingest”
Terminal window
knowflow ingest <url-or-text> [--source <type>]

Captures a URL or a plain-text note into raw/ as Markdown. --source (-s) defaults to auto, which detects the source type; use text for plain text.

Details worth knowing:

  • URL capture uses Jina Reader; YouTube and some logged-in platforms may also require yt-dlp or an authenticated browser workflow.
  • ingest does not synthesize wiki pages. It only stores the source material. Synthesis is your coding agent’s job, following the written contract at docs/agents/synthesize.md — a separate, visible step. This boundary is deliberate.

compose

Section titled “compose”
Terminal window
knowflow compose --list

Prints the raw files that have no wiki page yet — your agent’s work queue.

The list is derived, not stored: all files under raw/ minus every path that appears as a created_from pointer in the frontmatter of the four page directories. Zero state files, so the list self-heals — delete a synthesized page and its raw file is back on the list.

compose without --list prints usage and points at the synthesis contract.

check

Section titled “check”
Terminal window
knowflow check

Runs the eight-condition conformance gate over every page in the four page directories:

  • (a) the file’s directory matches its frontmatter type
  • (b) the body starts with an H1 equal to the frontmatter title
  • (c) required frontmatter fields are present (type, title, created, created_from, status)
  • (d) required sections exist, spelled exactly as in the templates and in template order
  • (e) no leftover {{…}} template placeholders
  • (f) (EXTRACTED)/(INFERRED) markers appear exactly once at the end of each key point on source/entity pages, and nowhere on concept/comparison pages
  • (g) acceptance thresholds hold (key-point counts, comparison dimensions and object counts)
  • (h) knowflow health comes back clean

Exits with code 1 on any violation, so it can gate CI or an agent’s synthesis loop. An empty wiki passes.

status

Section titled “status”
Terminal window
knowflow status

Prints a project overview: wiki article and line counts, raw material count, vector index state (pages embedded), graph node/edge counts, and whether an API key is configured. When pages are awaiting review, the output ends with the pending list — every status: pending page in the four page directories. Requires no API key.

health

Section titled “health”
Terminal window
knowflow health

Checks the wiki for:

  • Broken links — [[wikilinks]] and [markdown](links.md) pointing at missing files
  • Small files — pages below health.minFileSize bytes (default 100)
  • Orphan pages — pages no other page links to, excluding directories listed in health.excludeOrphanDirs

Pending pages (status: pending) are exempt from the orphan check — an unreviewed page with no inbound links is normal — while the broken-link and small-file checks apply to them in full.

Exits with code 1 when issues are found, so it can gate CI or agent workflows. Run fix to repair what it reports.

fix

Section titled “fix”
Terminal window
knowflow fix [--dry-run]

Repairs the issues health surfaces:

  • Cleans empty links such as [[entities/,]]
  • Creates missing entity/concept pages that links point to
  • Pads files below the minimum size
  • Auto-links orphan pages to index.md

Pending pages (status: pending) are never touched — a draft awaiting your review cannot be damaged by a fix.

--dry-run reports everything that would change without writing.

graph

Section titled “graph”
Terminal window
knowflow graph [--no-open]

Parses the wiki pages, extracts [[wikilink]] relationships, and writes graph.html (interactive viewer, loads vis-network from a CDN) plus graph.json (raw data). Frontmatter is stripped before parsing, and pending pages (status: pending) are skipped — no nodes, no edges, and links pointing at them do not resolve. The graph only ever contains reviewed content. No API key required. Opens the viewer in your browser unless --no-open is passed.

tags

Section titled “tags”
Terminal window
knowflow tags

Scans every wiki page for [[tag/<name>]] links and (re)builds hub pages at wiki/tag/<name>.md that index all pages carrying the tag. The rebuild is full and idempotent — safe to re-run whenever new tagged pages arrive.

index

Section titled “index”
Terminal window
knowflow index build [--incremental] [--stats]
knowflow index stats [--verbose] [--json]

Builds and inspects the vector index that powers semantic search.

  • build scans the wiki and embeds every page (files below 300 bytes are skipped; pending pages are skipped too — unreviewed content never reaches the search index). --incremental (-i) re-embeds only new or modified pages; --stats prints index statistics after the build.
  • stats reports page counts, embedding coverage, cache size, and token estimates — no API key needed. --verbose adds a per-file table; --json emits structured output.

Requires an embedding-provider API key (see Configuration for switching providers; the default is Zhipu).

query

Section titled “query”
Terminal window
knowflow query <text> [--top <n>]

Hybrid retrieval (vector search + keyword matching) over the wiki. --top (-n) controls result count (default 5, range 1–100).

Prerequisites:

  • An embedding-provider API key — by default a Zhipu AI key via ZHIPUAI_API_KEY or a project-root .env file
  • A vector index built with knowflow index build

ask

Section titled “ask”
Terminal window
knowflow ask <question>

Answers a question from retrieved Wiki context: the top matching pages are fetched, passed to a chat model as context, and the answer is printed with a numbered citation list. Requires the same key and a built index as query.

Configuration

Section titled “Configuration”

knowflow init writes a JSON .knowflowrc. All relative paths resolve from the directory containing that file.

{
  "wiki": { "root": "./wiki", "rawDir": "./raw" },
  "graph": { "output": "./graph/graph.html" },
  "health": { "minFileSize": 100, "excludeOrphanDirs": ["sources/"] }
}
  • health.excludeOrphanDirs — directories whose pages are expected to be unreferenced (daily-sync feeds, inboxes) and should not count as orphans
  • wiki.root / wiki.rawDir / graph.output — custom locations for the wiki, raw layer, and graph output

Graph generation, health checks, capture, and status never require an API key. Only index build, query, and ask do.

The embedding provider is pluggable via the optional embedding section. Presets fill in sensible defaults; every field can be overridden:

{ "embedding": { "provider": "openai" } }
{
  "embedding": {
    "provider": "custom",
    "baseUrl": "https://your-relay.example.com/v1",
    "model": "your-embedding-model",
    "apiKeyEnv": "RELAY_API_KEY",
    "chatModel": "your-chat-model"
  }
}
  • provider — zhipu (default), openai, or custom
  • baseUrl / model / dims / apiKeyEnv — endpoint overrides (preset defaults apply when omitted)
  • chatModel — the model behind knowflow ask

Malformed embedding sections fail fast with the offending field named.