Getting started
Pawl gives a repo one lint and format standard, run by the tools you choose, and a ratchet: the findings the repo already has are recorded once, and from then on only new ones fail.
Requirements
Section titled “Requirements”Node 22.18 or later.
Set up a repo
Section titled “Set up a repo”-
Run
initat the root of the repo.Terminal window npx @santi020k/pawl initinitlooks at the repo, shows what it will change, and asks before writing. In a terminal it offers a menu; in CI or under a coding agent it usesauto. -
Review the plan and accept it.
initwrites:biome.json, a few lines that extend the standard;checkandfixscripts inpackage.json;.vscode/settings.json, so the editor formats and fixes on save;.pawl/baseline.json, the findings the repo already has.
-
Commit the result, baseline included. From now on,
pawl checkfails only on new findings.
Here is init on a small npm project with two TypeScript files:
$ npx @santi020k/pawl init --yes --no-installDetected: JavaScript, npmLint: BiomeFormat: Biome Write biome.json (the pawl standard for Biome)Update package.json (scripts "check" and "fix")Write .vscode/settings.json (format on save with Biome)Write .vscode/extensions.json (recommend the Biome extension)Baseline: 6 existing findings recorded in .pawl/baseline.json. New ones will fail the check. Done. Run "pawl check" to check the code and "pawl fix" to fix it.Pawl never deletes or overwrites a tool config you already have. It tells you what you can remove.
| Mode | What it does |
|---|---|
auto (default) |
Biome lints and formats. An existing ESLint setup is left in place. |
keep |
Stay on the engine the repo uses today and add the ratchet on top. |
biome |
Biome only. Pawl stops running ESLint. |
Useful flags: --yes, --dry-run, --mode <mode>, --workflow (GitHub Actions: the check, and the doctor report as an artifact), --agents (a Claude Code hook, a Cursor hook where .cursor exists, and instructions in AGENTS.md), --hooks (a pre-commit hook), --no-editor, --no-install. The CLI reference lists them all.
Already on ESLint? pawl migrate turns your config into a pawl policy first.
Daily use
Section titled “Daily use”pawl check # lint, check formatting, apply the ratchetpawl check --changed # only files changed against HEADpawl fix # apply safe fixes and formatpawl baseline # accept the current findings as the new baselinepawl sync # rewrite biome.json after the policy changedpawl explain no-console # what a rule does, and its level in this repopawl doctor # check the setup and the tool versionsThe engines also work on their own: npx biome check and npx eslint . use the same config files.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | No new errors |
| 1 | New errors |
| 2 | A setup problem: an engine could not run, or, with --ci, the config drifted from the policy |
--ci is on automatically when the CI environment variable is true.
- The ratchet: what the baseline counts, and how to lock in improvements.
- Coding agents: give an agent findings it can act on.
- The policy: change the standard for one repo, or a whole company.
MIT licensed. Made by santi020k.