# Schemafier CLI

> Documentation index: [llms.min.txt](https://caseyrfsmith.github.io/scull/llms.min.txt) · Document manifest: [documents.json](https://caseyrfsmith.github.io/scull/documents.json)

Breadcrumbs: Reference > Schemafier CLI

`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](https://caseyrfsmith.github.io/scull/docs/reference/cli-reference.md).

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

```bash
scull-schemafier --help
scull-schemafier --version
```

## `run`

```text
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`

```text
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`

```text
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`

```text
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`

```text
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`

```text
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.

## `kg search`

```text
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`.

## Related guides

- [Getting started](https://caseyrfsmith.github.io/scull/docs/procedure/getting-started.md)
- [Build a schemaset](https://caseyrfsmith.github.io/scull/docs/procedure/adding-a-concept.md)
- [Review and fix](https://caseyrfsmith.github.io/scull/docs/procedure/procedure-review.md)
- [Build the index](https://caseyrfsmith.github.io/scull/docs/procedure/procedure-kg.md)
- [Project configuration](https://caseyrfsmith.github.io/scull/docs/reference/config-reference.md)