CLI

CLI reference

Entry point: cleanframe (console script from cleanframe.cli:main).

cleanframe --help
cleanframe <subcommand> --help

report

Profile a file and write an HTML report (no transforms applied).

cleanframe report examples/messy_customers.csv
cleanframe report data.csv --schema examples/customer.schema.yaml -o report.html

Common flags:

Flag	Meaning
--sheet NAME|IDX	Excel sheet by name or 0-based index
--columns A,B,C	Read a subset of columns (filter; keeps file order)
--nrows N	Read only the first N rows
--skiprows N	Skip N leading rows
--no-correct	Disable read-time encoding/delimiter auto-correction

clean

Full pipeline: profile → detect → plan → execute → save artifacts.

cleanframe clean examples/messy_customers.csv \
  --schema examples/customer.schema.yaml \
  --mode auto \
  --out-dir out/

Common flags:

Flag	Meaning
--schema PATH	Target schema YAML
--mode review|auto|strict	Confidence / failure policy
--llm provider/model	Optional LLM planner
--out-dir DIR	Write cleaned data, recipe, code, report
--out PATH	Cleaned data path only
--sheet NAME|IDX	Excel sheet by name or 0-based index
--columns A,B,C	Read a subset of columns (filter; keeps file order)
--nrows N	Read only the first N rows
--skiprows N	Skip N leading rows
--no-correct	Disable read-time encoding/delimiter auto-correction

A multi-sheet .xlsx auto-routes to workbook mode: cleanframe clean file.xlsx cleans every sheet; cleanframe apply file.xlsx --recipe wb.yaml replays a workbook recipe across sheets.

apply

Replay a saved recipe (deterministic, no LLM).

cleanframe apply new.csv --recipe customer.recipe.yaml --out clean.csv
cleanframe apply new.csv --recipe customer.recipe.yaml --force   # ignore drift (dangerous)

Flag	Meaning
--recipe PATH	Required recipe YAML
--mode	Execution mode
--force	Set on_drift=ignore
--out PATH	Output path
--sheet NAME|IDX	Excel sheet by name or 0-based index
--columns A,B,C	Read a subset of columns (filter; keeps file order)
--nrows N	Read only the first N rows
--skiprows N	Skip N leading rows
--chunksize N	Stream replay in N-row chunks (row-independent recipes only)

suggest

Detect drift and optionally write a patched recipe.

cleanframe suggest new.csv --recipe customer.recipe.yaml
cleanframe suggest new.csv --recipe customer.recipe.yaml --update -o patched.recipe.yaml

infer-schema

Draft a target schema from data.

cleanframe infer-schema examples/messy_customers.csv -o examples/customer.schema.yaml

detectors / ops

List registered plugins (built-ins + any you imported).

cleanframe detectors
cleanframe ops

Exit behaviour

• Drift with default apply → non-zero exit / raised error
• Missing input file → error
• Validation on_fail: error or strict mode → error