llmdoc / docs / cli

CLI reference

Invoke the external CLI as npx -y @tokenroll/llmdoc <command>. Pin the version in the package spec when a workflow must be reproducible.

Discover and read

tree: Dynamic map of root documents and topics.
index [--topic …] [--kind …]: Front-matter projection for document discovery.
search <query>: Lexical search across tracked knowledge, with Chinese word segmentation and an explicitly reported CJK-bigram fallback after zero lexical recall.
context --files <src…>: Map each source path to owner documents and required prerequisites, while reporting unmapped inputs explicitly.
show <path…>: Read selected document bodies.
serve: Start the local Viewer on 127.0.0.1 to inspect document structure, relations, and status.

Inspect validity

status: Validity, baseline, dirty, and growth signals.
delta: Changed code to impacted-document closure.
validate: Schema, structure, relations, links, code paths—including zero-match globs—ledger consistency, and optional startup config.

Mutate safely

new <path> --kind <kind>: Scaffold a V3 document, creating the first llmdoc/ directory at the nearest Git root when needed.
adopt <path…>: Register valid existing documents without rewriting their bodies.
mv <from> <to>: Move a document and transactionally rewrite internal references, ledger identity, and matching startup preload entries.
init-state: Seed the first ledger on a real Git HEAD; an unborn repository must create its initial commit first.
commit [--verified <path…> | --all]: Validate, commit changed prose, and refresh changed or verified revisions.
fingerprint --update <path…> | --all: Refresh validated revisions in the ledger.

Explicit operations and hooks

prune --report: Read-only convergence signals, including startup preload references that a manual merge or deletion must preserve.
upgrade: Explicit V2 migration diagnostics.
hook session-start | stop | compact: Read-only, fail-open host signals.

Startup context config

An optional llmdoc.config.json at the llmdoc workspace root—the nearest Git root that owns llmdoc/ in a Git repository—can make SessionStart proactively remind the agent to use the llmdoc skill and preload exact documents:

{
  "$schema": "https://llmdoc.tokenroll.ai/schemas/config.schema.json",
  "schema": "llmdoc.config/v1",
  "startup": {
    "remindSkill": true,
    "preload": ["architecture.mdx", "api-client/contracts.mdx"]
  }
}

The published schema enables editor validation. Operating guidance is enabled by default; set remindSkill to false to disable it. Cold-start preload order is preserved and has no llmdoc character or token budget. A final completion marker exposes likely host-side truncation; compact re-entry lists document IDs without injecting their bodies again.

validate rejects invalid or missing paths and warns while deduplicating normalized aliases. The hook remains fail-open: unreadable JSON/schema uses the default reminder, while preload-only errors preserve a valid remindSkill choice and skip preload.

All fixed CLI interface text is English. Chinese queries and repository document content remain supported and are returned unchanged.