Open source CLI • npm: @specferret/cli

Catch spec drift before it breaks production.

SpecFerret is a CLI that detects when API specs, contracts, and shipped behavior drift apart. Block risky commits with pre-commit checks and clear impact reports.

Install CLI Read the code

bun install -g @specferret/cli
ferret init
ferret lint

Why SpecFerret

AI ships code quickly

LLM-assisted development accelerates changes, but specs are often left behind. SpecFerret catches that mismatch before deploy.

Breaking vs non-breaking

It classifies drift so teams do not panic over harmless optional additions but do block true consumer-breaking changes.

Commit-time enforcement

Pre-commit hooks fail fast and keep bad contract changes out of main branch and out of production.

Use Cases

API teams

Detect shape changes in request and response contracts before clients break in staging or prod.

Multi-team repos

Backend changes can impact many consumers. SpecFerret shows direct and transitive impact in one report.

AI-assisted workflows

Keep generated code and contract docs in sync when rapid edits land through agents or pair-programming loops.

TypeScript shape checks

Validate declared types against contract expectations to reduce drift between docs and runtime reality.

How It Works

1. Define contracts in markdown with frontmatter schema fields.
2. Run ferret lint to detect drift and classify severity.
3. Use ferret review to inspect downstream impact and resolve safely.

Deterministic checks

Run ferret lint locally and in CI with reproducible drift detection and clear failure output.

Contract-aware impact

Review mode reports direct and transitive affected contracts so teams know exactly what to update.

Production-ready publishing

Trusted publishing with OIDC from GitHub Actions, versioned releases on npm, and evidence-backed validation runs.