# 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.