iftypeset/docs/16-cli-flags.md

iftypeset CLI flags (current v0 + parity notes)

This file captures the current CLI surface (as of 2026-01-04) from iftypeset --help and per-command --help, plus how config overrides are resolved. It is doc-only; no code/spec edits.

Sources used:

• app/CLI_SPEC.md (target contract)
• src/iftypeset/config.py (config precedence + keys)
• CLI help output for each command

Precedence and config

Order of precedence (highest → lowest):

1. CLI flags
2. iftypeset.yaml (in repo root or spec/..)
3. Hard defaults

Config sections:

• defaults: global fallback values
• Per-command section by name (hyphen → underscore)
  • render_html / render_pdf also read from render section

Supported config keys (from config.py):

• spec, out, profile, strict, format, fail_on, degraded_ok, fix, fix_mode, self_contained, engine, require_pdf, skip_pdf

Top-level flags

iftypeset [-h] [--config CONFIG] [--version]

• --config: path to iftypeset.yaml (default: ./iftypeset.yaml when present)
• --version: print version and exit

Command index (current)

Command	Purpose (short)	Required args	Key optional flags
validate-spec	Validate spec/rules; optional index build	none	--spec, --out, --build-indexes
profiles list	List profiles	none	--spec
gates show	Show QA gates	none	--spec, --profile, --strict
rules list	List rules with filters	none	--spec, --category, --enforcement, --severity, --tag
rules show	Show rule by id	rule_id	--spec
report	Coverage + report artifacts	none	--spec, --out, --strict, --build-indexes
doctor	Environment diagnostics	none	--spec, --out
bundle	Bundle out/ artifacts	none	--out, --bundle, --max-size-mb
run	Full pipeline	--input	--spec, --out, --profile, --strict, --format, --fail-on, --degraded-ok, --fix, --fix-mode, --self-contained, --engine, --require-pdf, --skip-pdf
lint	Lint + manual checklist	--input	--spec, --out, --profile, --format, --fail-on, --degraded-ok, --fix, --fix-mode
render-html	Deterministic HTML/CSS	--input	--spec, --out, --profile, --self-contained, --degraded-ok
render-pdf	Render PDF	--input	--spec, --out, --profile, --self-contained, --engine
qa	Post-render QA	none	--spec, --out, --html, --pdf, --profile, --strict, --format
emit-css	Emit profile CSS	none	--spec, --profile, --out

Detailed flags by command

validate-spec

iftypeset validate-spec [--spec SPEC] [--out OUT] [--build-indexes]

• --spec: spec root (default: ./spec)
• --out: output dir (default: ./out)
• --build-indexes: write indexes to spec/indexes/

profiles list

iftypeset profiles list [--spec SPEC]

gates show

iftypeset gates show [--spec SPEC] [--profile PROFILE] [--strict]

rules list

iftypeset rules list [--spec SPEC] [--category CATEGORY]
                      [--enforcement ENFORCEMENT] [--severity SEVERITY] [--tag TAG]

rules show

iftypeset rules show [--spec SPEC] rule_id

report

iftypeset report [--spec SPEC] [--out OUT] [--strict] [--build-indexes]

doctor

iftypeset doctor [--spec SPEC] [--out OUT]

bundle

iftypeset bundle [--out OUT] [--bundle BUNDLE] [--max-size-mb MAX_SIZE_MB]

run

iftypeset run --input INPUT [--spec SPEC] [--out OUT]
              [--profile PROFILE] [--strict] [--format {json,sarif,text}]
              [--fail-on {must,should,warn}] [--degraded-ok]
              [--fix] [--fix-mode {suggest,rewrite}] [--lint-fixed]
              [--self-contained] [--engine ENGINE]
              [--require-pdf] [--skip-pdf]

lint

iftypeset lint --input INPUT [--spec SPEC] [--out OUT]
               [--profile PROFILE] [--format {json,sarif,text}]
               [--fail-on {must,should,warn}] [--degraded-ok]
               [--fix] [--fix-mode {suggest,rewrite}] [--lint-fixed]

render-html

iftypeset render-html --input INPUT [--spec SPEC] [--out OUT]
                      [--profile PROFILE] [--self-contained] [--degraded-ok]

render-pdf

iftypeset render-pdf --input INPUT [--spec SPEC] [--out OUT]
                     [--profile PROFILE] [--self-contained] [--engine ENGINE]

qa

iftypeset qa [--spec SPEC] [--out OUT] [--html HTML] [--pdf PDF]
             [--profile PROFILE] [--strict] [--format {json,sarif}]

emit-css

iftypeset emit-css [--spec SPEC] [--profile PROFILE] [--out OUT]

Defaults (current)

• spec: ./spec
• out: ./out
• profile: web_pdf (unless overridden by config)
• engine: playwright (for run and render-pdf; use --engine auto for fallback)
• format: json (when supported)
• fail-on: must
• max-size-mb: 50

Exit codes (documented target)

The current CLI aligns to the exit code model in app/CLI_SPEC.md:

• 0: success
• 1: gates/thresholds failed (lint/qa/report)
• 2: config/schema error
• 3: renderer/tool error (pdf)

Parity notes vs app/CLI_SPEC.md

• --config exists at top-level and is honored by config.py.
• run includes --require-pdf and --skip-pdf, matching the spec.
• lint supports --fix and --fix-mode.
• lint supports --lint-fixed to lint the rewritten output when using --fix --fix-mode rewrite.
• qa supports --format sarif (HTML/PDF QA output).
• doctor, bundle, and emit-css are implemented and documented.

If new flags are added in code, update this file and the task board parity task.