For agents: Skip to article. Documentation index. Read this page as Markdown.
Scull
Reference

Schemafier CLI

Look up extraction, vocabulary, review, audit, and index-building commands.

Read as Markdown

scull-schemafier is the build-time interface. It turns a bounded docset into reviewed .schema.yaml artifacts and builds their derived search index. Query-time commands live in the separate scull CLI.

Install scull[build] for prose extraction. Deterministic spec and OpenAPI parsing use the core package; index construction additionally needs scull[search] or scull[local].

scull-schemafier --help
scull-schemafier --version

run

scull-schemafier run --concept NAME --out DIR
  [--docset DIR]
  [--spec FILE] [--oas FILE] [--prose DIR] [--vocab FILE]
  [--model MODEL] [--model-api-base URL]
  [--source-url FILENAME=URL] [--config FILE] [--force]

Runs extraction and deterministic reconciliation for one concept. At least one spec, OpenAPI, or prose input is required, along with a reviewed vocabulary. --docset discovers vocabulary.yaml, spec.json, openapi.{yaml,yml,json}, and prose/; explicit input flags take precedence.

--model is required only to extract prose. It defaults from SCULL_MODEL. --model-api-base defaults from SCULL_MODEL_API_BASE. Repeat --source-url to associate local Markdown filenames with canonical source URLs. Without --force, unchanged prose files recorded in the existing schema are skipped.

The schema is written even when review is required. Exit status is 0 for a review-clean result and 2 when needs_review: true requires a person to resolve warnings or conflicts.

finalize

scull-schemafier finalize [--schemas DIR] [--concept NAME ...]
  [--approve --reviewer IDENTITY --note TEXT]

Recomputes content hashes after manual edits, without extraction, an LLM, or source modification. The default is every schema under schemas/; repeat --concept to select artifacts. Rehashing alone does not grant approval or clear review state.

--approve explicitly accepts the selected artifacts' current content, warnings, and conflicts. It requires non-empty --reviewer and --note, sets needs_review: false, and writes _meta.review.{reviewer,note,approved_at,fingerprint}. The fingerprint becomes stale after any edit to fingerprint-covered content, warnings, conflicts, or review state. Approval records human review; it does not automatically establish factual correctness.

vocab bootstrap

scull-schemafier vocab bootstrap --concept NAME --out PROPOSAL.yaml
  [--docset DIR] [--spec FILE] [--oas FILE]
  [--prose DIR --model MODEL] [--model-api-base URL]

Creates a review-only vocabulary proposal. Structured inputs are handled deterministically; prose and alias suggestions are opt-in and require a model. The output path must be a new proposal file, not the reviewed vocabulary.yaml. Inspect canonical names, aliases, warnings, and provenance before promoting any entries.

audit-assignments

scull-schemafier audit-assignments --vocab vocabulary.yaml
  [--schemas DIR] [--concept NAME ...] [--json]

Rechecks committed prose-to-field assignments against the reviewed vocabulary without an LLM and without modifying files. The default schemaset directory is schemas. Exit status is 0 with no findings and 2 when review findings exist.

check

scull-schemafier check --concept NAME --out schemas/
  [--spec FILE] [--oas FILE] [--prose DIR]

Compares current source hashes with the hashes recorded in a schema. Pass every source type the concept actually uses. Exit status is 0 when current, 1 when stale or missing, and 2 for usage or read errors. This is the schema staleness gate for CI; it does not validate schema structure.

kg build

scull-schemafier kg build [--schemas DIR] [--out DIR] [--force] [--release]

Builds or incrementally updates the v2 index. Defaults are schemas/ and kg/. The builder validates schema content and reuses a concept's published vector rows only when its provider identity, chunker version, and exact chunk fingerprint match. Removed concepts are pruned. A provider or model identity change forces a complete rebuild automatically. --force explicitly re-embeds everything and is the recovery path for corrupt or unsupported indexes. V1 indexes remain readable, but builds write v2.

--release first requires a non-empty schemaset whose schemas are structurally valid, have current content hashes, have needs_review: false, and carry matching recorded approvals. Without this flag, development builds remain possible for artifacts still under review.

Index builds stage a complete immutable generation and switch kg/CURRENT only after validation, so a failed build leaves the previously published generation readable. Each generation contains one normalized float32 matrix, ordered node records with exact embedded text, concept partitions, schema catalog metadata, and the dedup report. Dedup comparison uses bounded blocks.

scull-schemafier kg search "QUERY" [--kg DIR] [--top-k N]

Runs the same local query engine used by scull search and prints compact node IDs and scores. This command is primarily a builder smoke test; agent and user integrations should normally use the query CLI or FileSchemaProvider.