# CLI Specification

The CLI is designed for CI use: deterministic outputs, stable exit codes, and JSON artifacts for tooling.

## Common flags (all commands)

This is the *target* contract; v0 currently implements a subset per-command.

Precedence (highest → lowest): CLI flags → `iftypeset.yaml` → hard defaults.

* `--spec <dir>`: Spec root directory (default: `spec/`).
* `--input <path>`: Markdown file or directory (where applicable).
* `--out <dir>`: Output directory (default: `out/`).
* `--profile <name>`: One of: `web_pdf`, `print_pdf`, `dense_tech`, `memo`, `slide_deck`, `webtypography_nc` (non-commercial).
* `--config <path>`: Path to `iftypeset.yaml` (defaults to `./iftypeset.yaml` when present).
* `--engine <auto|playwright|wkhtmltopdf|weasyprint>`: Preferred PDF engine (default: `playwright`; `auto` is treated as `playwright`; Chromium CLI engine is banned).
* `--font-dir <dir>`: Additional font directory (repeatable) to supply corporate fonts at render time.
* `--strict-fonts`: Enforce a fonts contract for PDF rendering (fail if primary profile fonts are missing or not embedded in the PDF).
* `--strict`: Use strict thresholds in `spec/quality_gates.yaml` (QA/report).
* `--format <json|sarif|text>`: Lint output format.
* `--fail-on <must|should|warn>`: Lowest severity that fails `lint` (default: `must`).
* `--degraded-ok`: Allow degraded mode without failing (lint/render-html).
* `--fix`: Apply safe deterministic fixes (lint/run).
* `--fix-mode <suggest|rewrite>`: Fix mode for `--fix` (lint/run).
* `--lint-fixed`: When rewriting fixes, lint the fixed output instead of the original (lint/run).
* `--version`: Print tool version and exit.

## Command: `validate-spec`

Purpose:

* Validate YAML/JSON spec files and (when present) rule NDJSON batches.

Outputs:

* `out/spec-validation.json`

Exit codes:

* `0`: ok
* `2`: config/schema error

## Command: `profiles list`

Purpose:

* List available profile ids in the current spec.

Outputs:

* JSON to stdout (`profiles: [...]`)

Exit codes:

* `0`: ok
* `2`: config error

## Command: `gates show`

Purpose:

* Show QA gate thresholds for a profile (`--strict` selects strict mode).

Outputs:

* JSON to stdout (`gates: {...}`)

Exit codes:

* `0`: ok
* `2`: config error

## Command: `rules list` / `rules show`

Purpose:

* List rules with basic filters, or show a full rule record by id.

Outputs:

* JSON to stdout (`rules: [...]` or `rule: {...}`)

Exit codes:

* `0`: ok
* `2`: config error / rule not found

## Command: `report`

Purpose:

* Produce a consolidated report (coverage + indexes status).

Outputs:

* `out/coverage-report.json`
* `out/coverage-summary.md`
* `out/report/index.html`

Exit codes:

* `0`: report built
* `1`: coverage floor violated (only when rule batches exist)
* `2`: config/schema error

## Command: `doctor`

Purpose:

* Emit environment and determinism diagnostics (renderer, Poppler, fonts, locale).

Outputs:

* `out/doctor.json`
* `out/doctor.md`

Exit codes:

* `0`: ok
* `2`: config error

## Command: `bundle`

Purpose:

* Create a portable tarball of `out/` artifacts with a sha256 manifest for external review.

Outputs:

* `out/bundle-manifest.json`
* `out/iftypeset-bundle.tar.gz` (default; override with `--bundle`)

Exit codes:

* `0`: ok

Notes:

* Files larger than `--max-size-mb` are skipped and recorded in the manifest.
* Bundle entries are sorted and stored with fixed mtimes for deterministic output.

## Command: `run`

Purpose:

* One-shot CI pipeline: validate → lint → render-html → render-pdf (best effort) → qa → report.

Outputs:

* All artifacts from the underlying commands.
* `out/run-summary.json`
* When `--input` is a directory or glob, per-doc artifacts are written under `out/docs/<relpath>/` and
  `out/report/index.html` becomes a multi-doc index.

Exit codes:

* `0`: pipeline ok (lint + qa + report passed)
* `1`: gate failed (lint/qa/report/degraded render-html)
* `2`: config error
* `3`: renderer/tool error (only when `--require-pdf` is set)

Notes:

* PDF rendering failures are recorded as warnings in `run-summary.json` and do not fail the run **unless**
  `--require-pdf` is set.
* Use `--skip-pdf` to omit PDF rendering entirely when only HTML QA is desired.
* Use `--engine` to force a specific renderer (useful for reproducible CI).
* Use `--font-dir` to mount a corporate fonts directory and avoid fallback fonts.
* Use `--strict-fonts` (or profile `fonts.require_primary: true`) to fail fast if font fallback would occur.

## Command: `lint`

Purpose:

* Parse Markdown into a minimal block AST (headings, paragraphs, lists, code fences, tables).
* Emit deterministic diagnostics and a manual checklist derived from the registry.

Outputs:

* `out/lint-report.json`
* `out/manual-checklist.md`
* `out/manual-checklist.json`
* `out/degraded-mode-report.json` (only when degraded mode triggers)
* `out/lint-report.sarif` (only when `--format sarif`)
* `out/fix-suggestions.json` (only when `--fix --fix-mode suggest`)
* `out/fixed/*.md` (only when `--fix --fix-mode rewrite`)

Notes:

* `--lint-fixed` re-lints the rewritten output so diagnostics reflect the fixed text.

Exit codes:

* `0`: ok
* `1`: lint failed (fail-on threshold exceeded, or degraded mode without `--degraded-ok`)
* `2`: config error

## Command: `render-html`

Purpose:

* Render Markdown to deterministic HTML and CSS based on a profile.

Outputs:

* `out/render.html`
* `out/render.css`
* `out/typeset-report.json`
* `out/degraded-mode-report.json` (only when degraded mode triggers)

Exit codes:

* `0`: ok
* `1`: degraded mode without `--degraded-ok`
* `2`: config error

## Command: `render-pdf`

Purpose:

* Render Markdown to PDF using the configured engine (default: `playwright`; `--engine auto` is treated as `playwright`; Chromium CLI engine is not supported).

Outputs:

* `out/render.html`
* `out/render.css`
* `out/typeset-report.json`
* `out/render-log.json`
* `out/render.pdf` (only when rendering succeeds)

Exit codes:

* `0`: ok
* `3`: renderer missing or engine error (see `out/render-log.json`)
* `2`: config error

Notes:

* Use `--engine` to force a specific renderer (e.g., `--engine wkhtmltopdf`).
* Use `--font-dir` to supply additional font directories for the renderer (e.g., corporate fonts).
* Use `--strict-fonts` (or profile `fonts.require_primary: true`) to prevent silent font fallbacks in shipped PDFs.

## Command: `qa`

Purpose:

* Run deterministic post-render QA checks (HTML analysis v0) and enforce numeric gates from `spec/quality_gates.yaml`.

Args:

* `--out <dir>`: output directory containing `render.html` / `render.pdf` (default: `out/`)
* `--html <path>`: HTML to analyze (default: `<out>/render.html`)
* `--pdf <path>`: optional PDF path for reporting (default: `<out>/render.pdf`)
* `--strict`: use strict thresholds from `spec/quality_gates.yaml`
* `--format <json|sarif>`: optional SARIF output for CI annotations

Outputs:

* `out/layout-report.json`
* `out/qa-report.json`
* `out/qa-report.sarif` (when `--format sarif`)

Exit codes:

* `0`: gates pass
* `1`: gates fail
* `2`: config error / missing HTML input