Skip to content

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.

Node 22.18 or later.

  1. Run init at the root of the repo.

    Terminal window
    npx @santi020k/pawl init

    init looks 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 uses auto.

  2. Review the plan and accept it. init writes:

    • biome.json, a few lines that extend the standard;
    • check and fix scripts in package.json;
    • .vscode/settings.json, so the editor formats and fixes on save;
    • .pawl/baseline.json, the findings the repo already has.
  3. Commit the result, baseline included. From now on, pawl check fails 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.

Terminal window
pawl check # lint, check formatting, apply the ratchet
pawl check --changed # only files changed against HEAD
pawl fix # apply safe fixes and format
pawl baseline # accept the current findings as the new baseline
pawl sync # rewrite biome.json after the policy changed
pawl explain no-console # what a rule does, and its level in this repo
pawl doctor # check the setup and the tool versions

The engines also work on their own: npx biome check and npx eslint . use the same config files.

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.