CLI reference #

usage: lintlang scan [-h] [--discover [ROOT]] [--stdin-filename PATH]
                     [--allow-empty] [--show-all] [--fix] [--dry-run]
                     [--backup] [--allow-uninspected]
                     [--patterns {H1,H2,H3,H4,H5,H6,H7} [{H1,H2,H3,H4,H5,H6,H7} ...]]
                     [--format {terminal,markdown,json,sarif,gitlab}]
                     [--no-suggestions]
                     [--min-severity {critical,high,medium,low,info}]
                     [--fail-under FAIL_UNDER] [--fail-on {fail,review}]
                     [--exclude EXCLUDE [EXCLUDE ...]] [--baseline BASELINE |
                     --write-baseline WRITE_BASELINE]
                     [files ...]

Scan agent configs and embedded language in Python pipelines. Confidence
explains HERM coverage proxies; it is separate from the structural
PASS/REVIEW/FAIL verdict.

positional arguments:
  files                 Language-bearing inputs: YAML, JSON, text, or Python
                        (.py uses AST extraction for embedded prompts/pipeline
                        artifacts; not general Python code linting). Use '-'
                        exactly once with --stdin-filename to scan one
                        document from standard input.

options:
  -h, --help            show this help message and exit
  --discover [ROOT]     Also scan recognized agent instruction files found
                        under ROOT (default: '.'): AGENTS.md, CLAUDE.md,
                        GEMINI.md, SKILL.md, agent.yaml/.yml/.json,
                        .github/copilot-instructions.md, and *.instructions.md
                        under .github/instructions/. Symlinks are not
                        followed; a skipped one is named on stderr. Explicit
                        inputs still win and are unioned with the discovered
                        set.
  --stdin-filename PATH
                        Virtual path for the single '-' input. It selects the
                        parser and supplies the source identity used by
                        locations, JSON/SARIF output, and baseline matching.
                        The path is never opened.
  --allow-empty         Exit 0 when the scan inspected zero files (default:
                        that is an input error)
  --show-all            Terminal output: list every finding (default: 5 per
                        finding code, then a count)
  --fix                 Show and apply the exact supported standalone
                        verbosity rewrite
  --dry-run             With --fix, show the exact diff without writing the
                        file
  --backup              With --fix, save original bytes as FILE.lintlang.bak
                        before writing (never overwrite)
  --allow-uninspected   Report a named file whose tool-like content could not
                        be inspected as SKIPPED (default: that is an input
                        error, because a named file that was not read must
                        never look clean). Also accept a scan in which every
                        file was SKIPPED.
  --patterns, -p {H1,H2,H3,H4,H5,H6,H7} [{H1,H2,H3,H4,H5,H6,H7} ...]
                        Only check specific structural patterns (default: all)
  --format, -f {terminal,markdown,json,sarif,gitlab}
                        Output format (default: terminal)
  --no-suggestions      Hide fix suggestions
  --min-severity {critical,high,medium,low,info}
                        Minimum severity for structural findings (default:
                        info)
  --fail-under FAIL_UNDER
                        Exit with code 1 if quality score is below this
                        threshold (legacy; prefer --fail-on)
  --fail-on {fail,review}
                        Exit with code 1 on verdict: 'fail' (any
                        CRITICAL/HIGH) or 'review' (any MEDIUM+). Default: no
                        exit on verdict.
  --exclude EXCLUDE [EXCLUDE ...]
                        Glob patterns to exclude (e.g., 'CHANGELOG.md'
                        'docs/**'). Non-prompt files (README, LICENSE, etc.)
                        are skipped automatically.
  --baseline BASELINE   Acknowledge exact existing findings from a reviewed
                        baseline; report new findings
  --write-baseline WRITE_BASELINE
                        Record current findings to a new baseline file without
                        overwriting an existing file

Low confidence may reflect non-prompt reference material or an undetected
input boundary. Reports explain the detected drivers; JSON includes
herm.confidence_breakdown. Confidence bands use high >=90%, medium >=75%, and
low <75% coverage. Auto-fix supports only a direct standalone 'Don't be
verbose' instruction (also with a curly apostrophe) as the first body line
after a file-leading top-level '# Instructions' heading and blanks. Other
headings, preambles, and malformed scope fail closed. H1/H2 inference,
security negatives, priority rules, and cross-file conflicts remain manual.
--fix accepts one explicit .md, .txt, or .prompt file and terminal output
only.