clifingerprint
Local-first CLI contract recording and comparison.
clifingerprint runs configured command probes, records the observable CLI contract, and compares fresh runs against a saved baseline. It is meant for maintainers who want release checks for help text, options, examples, exit codes, stdout/stderr snippets, and package metadata.
Install
Development and release verification cover Node.js 20.19, 22, and 24 with npm 10. The repository pins npm 10.9.4 so clean installs use the lockfile's verified package-manager version. scripts/validate.sh follows this declared npm toolchain even when other package managers are installed:
npx --yes npm@10.9.4 ciRun from the repository:
node src/cli.js --helpThe package exposes the cli-fp binary when installed.
Quick Start: Record A Fingerprint
node src/cli.js record clifingerprint.yaml --output fingerprint.jsonrecord executes every non-skipped probe in the config and writes a JSON fingerprint, creating missing parent directories in the --output path. Intentionally skipped probes remain in the fingerprint, and their expected exit code is not evaluated. It exits with code 1 without saving when a command cannot be executed, a probe times out, or a completed probe does not match its expectedExitCode.
Compare Against A Baseline
node src/cli.js compare fingerprint.json clifingerprint.yamlcompare runs the probes again and exits with code 1 when the current contract differs from the baseline. A fresh execution error, timeout, or expectedExitCode mismatch also fails comparison even when the saved baseline contains the same failure state, preventing broken probes from being reported as compatible.
Show A Summary
node src/cli.js show fingerprint.jsonEach probe is marked ✓ when it completed successfully, including an expected nonzero exit, ○ when it was intentionally skipped, or ✗ for an expected-exit mismatch, timeout, execution error, or unexpected nonzero exit. The summary names timeout and execution-error states and shows both actual and expected codes for an exit mismatch.