iftypeset/app/CLI_SPEC.md

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.

• --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 (where applicable).
• --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).
• --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
• 4: config/schema error
• 5: internal error

Command: report

Purpose:

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

Outputs:

• out/coverage-report.json
• out/coverage-summary.md

Exit codes:

• 0: report built
• 2: coverage floor violated (only when rule batches exist)
• 4: config/schema error
• 5: internal error

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)

Exit codes:

• 0: ok
• 2: lint failed (fail-on threshold exceeded, or degraded mode without --degraded-ok)
• 4: 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
• 2: degraded mode without --degraded-ok
• 4: config error

Command: render-pdf

Purpose:

• Render Markdown to PDF using the first available engine (playwright/chromium/wkhtmltopdf/weasyprint).

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)
• 4: config error

Command: qa

Purpose:

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

Outputs:

• out/layout-report.json
• out/qa-report.json

Exit codes:

• 0: gates pass
• 2: gates fail
• 4: config error / missing out/render.html