cofferdam

Appearance

Command-Line Help for cofferdam ​

This document contains the help content for the cofferdam command-line program.

Command Overview:

cofferdam ​

TypeScript code-quality analyzer

Usage: cofferdam <COMMAND>

Subcommands: ​
  • hello — Print the project banner
  • check — Run all checks against files or directories. With no arguments, walks the current directory
  • baseline — Manage the baseline of accepted findings. The baseline lets you drop cofferdam into an existing project without immediately failing CI on every pre-existing finding
  • explain — Print the metadata and prose explanation for one check (built-in or plugin). Use this when a finding's check ID isn't self-explanatory and you want the rationale, default severity, configurable options, and any relevant flags without leaving the terminal. Add --full to also render the companion markdown body (motivation, examples, config snippets) sourced from the check catalog
  • init — Scaffold cofferdam.toml + .cofferdam/baseline.json + .gitignore entries so a new project has a working cofferdam check after one command. Refuses to overwrite an existing cofferdam.toml without --force
  • doctor — Diagnose install and configuration issues. Reports each check as ✓ / ⚠ / ✗ with a one-line remediation hint on failure. Exit 0 on all-pass, 1 if any check fails. Diagnostic only — never modifies files
  • watch — Re-analyze on file change (cd-9hp.4 cp1b). Discovers files once, registers a recursive filesystem watcher, and re-runs the engine on each detected change. A shared in-memory parse cache survives across iterations, so unchanged files skip parse on every subsequent pass. Text output only — for scripted use cases keep cofferdam check
  • fix — Apply mechanical autofixes for supported checks. Runs the engine against the given paths, groups fixable findings by file, applies edits in reverse byte-offset order, and writes each modified file atomically (write to a temp path then rename). Unsupported checks are silently skipped. Prints a summary to stderr
  • advise — JIT architectural advisory for agents — emit the rules that apply to a given file or directory, INDEPENDENT of whether any current code violates them. Designed for agentic edit loops: an LLM agent shells out before editing a file, gets back layer membership and per-rule constraints, and adjusts its plan before writing code. Static projection — does not parse, does not run checks, does not build the project graph. With no arguments, walks the current directory
  • gen-docs — Regenerate the docs catalog from CheckMeta. Writes per-check markdown files, a schema-stable JSON index, an llms.txt root index, and the CLI reference page (from clap-markdown). Use --check to fail when the committed files are out of date — same shape as cargo fmt --check
  • lsp — Run the Language Server Protocol server over stdio (cd-9hp.4 cp5). Editors that speak LSP — VS Code (via the bundled extension stub at editors/vscode), Helix, neovim — connect and receive workspace diagnostics on save. The server hydrates the cp4 disk cache at startup and persists it on shutdown. Run with no arguments; the LSP transport handles its own configuration via the standard initialize request

cofferdam hello ​

Print the project banner

Usage: cofferdam hello

cofferdam check ​

Run all checks against files or directories. With no arguments, walks the current directory

Usage: cofferdam check [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to analyze. Defaults to .
Options: ​

  • --hidden — Walk hidden files/directories (default: skip)

  • --no-ignore — Disable .gitignore / .cofferdamignore filtering

  • --format <FORMAT> — Output format. Default: text. With --robot and no explicit --format, defaults to json

    Possible values:

    • text: Human-readable text grouped by category (default)
    • json: Machine-readable JSON. Stable schema, no ANSI, no decorative output
    • compact: Pipe-delimited line-per-finding format. One header line followed by one record per finding. Most token-economical — use when shovelling findings into an AI prompt
    • sarif: SARIF 2.1.0 — OASIS-standard JSON for static-analysis tools. Upload directly to GitHub Code Scanning via github/codeql-action/upload-sarif, or feed Azure DevOps, GitLab, SonarQube, the VS Code Sarif Viewer, etc

  • --robot — Default to a machine-readable format when --format is not set. Token-economical output for AI agents — pairs with --format=compact for the smallest output by far

  • --pretty — Pretty-print JSON output (only with --format=json / --robot)

  • --baseline <PATH> — Path to a baseline file. Defaults to .cofferdam/baseline.json when that file exists. Conflicts with --no-baseline

  • --no-baseline — Disable baseline detection entirely. Equivalent to running without a baseline file present

  • --fail-on-new — Only fail (exit 1) on findings absent from the baseline. Implicit when a baseline is active; pass explicitly to document intent in CI scripts. Has no effect without a baseline

  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config

  • --no-config — Disable config-file discovery entirely. Equivalent to running without a cofferdam.toml present

  • --since <GIT-REF> — PR mode — report only findings on files changed in <git-ref>...HEAD. The full project tree is still analysed for cross-file soundness (OrphanExport, DeadExport, import cycles); only the reported findings are filtered to the diff

  • --fail-on <LEVEL> — Severity threshold for the exit-1 gate. Findings below this level still print; the process only exits 1 if at least one finding is at this level or above. Baselined findings never trigger the gate

    Default value: medium

    Possible values: info, low, medium, high, critical

  • --max-issues <N> — Cap rendered findings at the top N by sort priority. The CI gate (--fail-on) still considers the full unbounded set, so truncating output never hides a failure. Pairs with --quiet for compact CI output. 0 disables the cap (default)

    Default value: 0

  • --quiet — Suppress informational output: the trailing N finding(s) summary line, "no TypeScript files found" hints, and the "(showing N of M)" truncation note. Findings, warnings, and errors still print. Has no effect on JSON output (which is already terse)

  • --hide-baselined — Hide baselined findings from text output. The summary line still reports (N new, M baselined) counts so the CI gate remains visible. Has no effect on --format=json (which always includes the per-finding baselined flag) or on the --fail-on gate (which already ignores baselined findings). Useful for routine local runs against repos with substantial baselines (cd-k23 / gh #11)

  • --cache-dir <PATH> — Directory for the disk-backed findings/run cache (cd-9hp.4 cp4). Defaults to .cofferdam/cache/ under CWD. Each cofferdam build writes to a version-scoped subdir so an upgrade invalidates prior caches automatically. Add the directory to .gitignore

  • --no-cache — Disable disk caching entirely. Equivalent to deleting the cache directory before each run. Cold cost only; no correctness difference

cofferdam baseline ​

Manage the baseline of accepted findings. The baseline lets you drop cofferdam into an existing project without immediately failing CI on every pre-existing finding

Usage: cofferdam baseline <COMMAND>

Subcommands: ​
  • write — Run the analyzer and write the current set of findings to the baseline file. Subsequent cofferdam check runs ignore these findings for CI-gating purposes; they still print as [baselined] so the team can chip away at them
  • lint — Report baseline entries that are also suppressed inline
  • diff — Compute delta between two baselines

cofferdam baseline write ​

Run the analyzer and write the current set of findings to the baseline file. Subsequent cofferdam check runs ignore these findings for CI-gating purposes; they still print as [baselined] so the team can chip away at them

Usage: cofferdam baseline write [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to analyze. Defaults to .
Options: ​
  • --hidden — Walk hidden files/directories (default: skip)
  • --no-ignore — Disable .gitignore / .cofferdamignore filtering
  • --output <PATH> — Where to write the baseline. Defaults to .cofferdam/baseline.json in the current directory
  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config
  • --no-config — Disable config-file discovery entirely
  • --robot — Machine-readable JSON output. Emits a delta block when a prior baseline existed; omitted on first run
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam baseline lint ​

Report baseline entries that are also suppressed inline.

A "dual-state" entry is silenced twice — once by the baseline and once by an inline directive — which wastes signal and obscures the true technical-debt posture. Exit 0 if none found, 1 if any (so it is wireable into CI for teams that want to enforce hygiene).

Usage: cofferdam baseline lint [OPTIONS]

Options: ​
  • --robot — Machine-readable JSON. Schema: { dual_state: [...], summary: { count } }
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam baseline diff ​

Compute delta between two baselines.

With two explicit paths: compares them directly. Useful for triage and PR review outside the baseline write path.

Usage: cofferdam baseline diff [OPTIONS] [BASELINE_A] [BASELINE_B]

Arguments: ​
  • <BASELINE_A> — First baseline path
  • <BASELINE_B> — Second baseline path
Options: ​
  • --robot — Machine-readable JSON
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam explain ​

Print the metadata and prose explanation for one check (built-in or plugin). Use this when a finding's check ID isn't self-explanatory and you want the rationale, default severity, configurable options, and any relevant flags without leaving the terminal. Add --full to also render the companion markdown body (motivation, examples, config snippets) sourced from the check catalog.

Plugin checks: explain discovers plugin-declared checks from cofferdam.toml's plugins = [...] and renders their explanation (and body for --full) the same way as built-ins. Plugins must be loadable from the current working directory; otherwise the unknown-check fallback prints suggestions only from built-ins.

Usage: cofferdam explain [OPTIONS] <CHECK_ID>

Arguments: ​
  • <CHECK_ID> — Dotted check ID, e.g. Warning.TripleEquals. If unknown, the CLI prints the closest matches (substring on the ID) or the full list when nothing matches
Options: ​
  • --robot — Machine-readable JSON. Schema mirrors CheckMeta fields
  • --pretty — Pretty-print JSON output. No effect without --robot
  • --full — Print the full companion markdown body after the metadata summary. In --robot mode, includes a body field in the JSON output. Frontmatter is stripped before display
  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config
  • --no-config — Disable config-file discovery entirely. Plugin checks won't be resolved

cofferdam init ​

Scaffold cofferdam.toml + .cofferdam/baseline.json + .gitignore entries so a new project has a working cofferdam check after one command. Refuses to overwrite an existing cofferdam.toml without --force

Usage: cofferdam init [OPTIONS] [PATH]

Arguments: ​

  • <PATH> — Project root to initialise. Defaults to the current directory

    Default value: .

Options: ​
  • --force — Overwrite an existing cofferdam.toml
  • --baseline — Capture the current set of findings as the baseline. Skip the interactive prompt
  • --no-baseline — Do not capture a baseline. Skip the interactive prompt
  • --robot — Machine-readable JSON summary instead of human output. No prompts; defaults to capturing a baseline

cofferdam doctor ​

Diagnose install and configuration issues. Reports each check as ✓ / ⚠ / ✗ with a one-line remediation hint on failure. Exit 0 on all-pass, 1 if any check fails. Diagnostic only — never modifies files

Usage: cofferdam doctor [OPTIONS]

Options: ​
  • --robot — Machine-readable JSON output. Schema mirrors the per-check CheckResult and a top-level summary tally
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam watch ​

Re-analyze on file change (cd-9hp.4 cp1b). Discovers files once, registers a recursive filesystem watcher, and re-runs the engine on each detected change. A shared in-memory parse cache survives across iterations, so unchanged files skip parse on every subsequent pass. Text output only — for scripted use cases keep cofferdam check

Usage: cofferdam watch [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to watch. Defaults to .
Options: ​

  • --hidden — Walk hidden files/directories

  • --no-ignore — Disable .gitignore / .cofferdamignore filtering

  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory

  • --no-config — Disable config-file discovery entirely

  • --debounce <MS> — Debounce filesystem events by this many milliseconds. Lower = faster reaction to a save; higher = fewer duplicate runs when an editor emits multiple events per save. 100 ms is the typical sweet spot

    Default value: 100

cofferdam fix ​

Apply mechanical autofixes for supported checks. Runs the engine against the given paths, groups fixable findings by file, applies edits in reverse byte-offset order, and writes each modified file atomically (write to a temp path then rename). Unsupported checks are silently skipped. Prints a summary to stderr

Usage: cofferdam fix [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to fix. Defaults to .
Options: ​
  • --hidden — Walk hidden files/directories (default: skip)
  • --no-ignore — Disable .gitignore / .cofferdamignore filtering
  • --dry-run — Preview mode — discover all fixable findings and print what WOULD be changed, but do not modify any file. Exits 0. Use this to audit autofix coverage before committing to a write
  • --robot — Machine-readable JSON output. Emits a structured report instead of human-readable lines. With --dry-run, no files are written; the JSON describes what would change
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam advise ​

JIT architectural advisory for agents — emit the rules that apply to a given file or directory, INDEPENDENT of whether any current code violates them. Designed for agentic edit loops: an LLM agent shells out before editing a file, gets back layer membership and per-rule constraints, and adjusts its plan before writing code. Static projection — does not parse, does not run checks, does not build the project graph. With no arguments, walks the current directory

Usage: cofferdam advise [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files, directories, or globs to advise on. Defaults to .. Glob patterns (src/**/*.ts) work; shell expansion is honoured first, then the CLI's own globset matcher
Options: ​

  • --format <FORMAT> — Output format. Default: text. With --robot and no explicit --format, defaults to json

    Possible values:

    • text: Human-readable text grouped by file (default)
    • json: Machine-readable JSON array. One object per file

  • --robot — Default to a machine-readable JSON array when --format is not set. Token-economical output for AI agents

  • --pretty — Pretty-print JSON output

  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config

  • --no-config — Disable config-file discovery entirely

  • --hidden — Walk hidden files/directories (default: skip)

  • --no-ignore — Disable .gitignore / .cofferdamignore filtering

  • --diff <GIT-REF> — Diff mode — run the engine and any configured plugins against the working tree AND the state at <git-ref>, then report rules that WOULD fire if the change were committed (would_fire) plus rules that currently fire on <git-ref> but are cleared by the change (would_clear). Output is always JSON when this flag is set; --format is ignored

  • --fail-on <LEVEL> — Severity gate for --diff mode. When set, the process exits 1 if any would_fire entry is at or above this level. would_clear never gates. No effect without --diff

    Possible values: info, low, medium, high, critical

cofferdam gen-docs ​

Regenerate the docs catalog from CheckMeta. Writes per-check markdown files, a schema-stable JSON index, an llms.txt root index, and the CLI reference page (from clap-markdown). Use --check to fail when the committed files are out of date — same shape as cargo fmt --check

Usage: cofferdam gen-docs [OPTIONS]

Options: ​

  • --out <DIR> — Output directory. The catalog lands at <out>/checks.json, <out>/checks/<id>.md, <out>/checks/index.md, <out>/llms.txt, <out>/reference/cli.md

    Default value: docs

  • --check — Don't write — only fail (exit 1) if the existing files would change. The CI gate uses this

cofferdam lsp ​

Run the Language Server Protocol server over stdio (cd-9hp.4 cp5). Editors that speak LSP — VS Code (via the bundled extension stub at editors/vscode), Helix, neovim — connect and receive workspace diagnostics on save. The server hydrates the cp4 disk cache at startup and persists it on shutdown. Run with no arguments; the LSP transport handles its own configuration via the standard initialize request

Usage: cofferdam lsp

This document was generated automatically by clap-markdown.

MIT License

Copyright © 2026 Thomas Dickson