Check a FastAPI backend

You have a FastAPI backend and want chisel to find architecture violations in it. This guide installs the Python CLI, runs a check, and explains how to read the output.

Install

pip install chisel           # or: pipx install chisel,  uv tool install chisel
chisel --version

Requires Python ≥ 3.11. Runtime deps (grimp, radon, typer, rich) install automatically.

Run a check

Point chisel check at your project root. Default path is ..

chisel check ./your-backend

Non-zero exit on any ERROR-level violation. That’s what makes it safe to gate commits and CI on.

Strict mode

--strict (the default) additionally enforces project-structure rules: src-layout, pyproject.toml-only, build-config. Turn it off if you’re checking a project that doesn’t follow src-layout yet and you only want the code-level rules.

chisel check ./your-backend --strict          # default: also enforce layout
chisel check ./your-backend --no-strict       # code rules only

Read the output

Coloured, grouped by category, one block per violation. Each violation names the file, line, rule ID, and a short message.

chisel check ./your-backend

For scripts, agents, or CI, ask for JSON; see Understand a violation for how to read the deduplicated --json output.

What’s next

• Understand a violation: read a rule’s description and fix guidance with chisel explain.
• Turn off a rule for a file: exempt legacy files or justified exceptions.
• Block violations before commit: wire chisel into a pre-commit hook.
• Python rules reference: every rule, grouped by category.