A Perch scan highlights checkout, cart, inventory, and token-generation problems in an example project.

This scan checked a small order service with deliberately planted bugs. It returned 19 findings across five files. The GIF highlights four; the full output records the run.

Choose what to check

perch scan checks defects, security, and your custom rules by default. Use --filter type= to choose the questions for a run.

Type Checks Example
defect Incorrect behavior, ordering, missing values, and error handling Checkout accepts an incomplete cart
security Authorization, injection, unsafe input handling, and other security classes Order cancellation without an owner check
lint Rules from perch.yaml Refunds and other behavior requirements
docs Method documentation Comments that match the implementation
refactor Method structure Enable explicitly when reviewing complexity or duplication

Run one type

After setting up Perch, run one type from your Git repository:

perch scan --filter type=defect
perch scan --filter type=security
perch scan --filter type=lint

Each command makes a separate scan. scan reads code at HEAD; commit a change before rescanning it. For an uncommitted edit, use perch check path::method or perch check path for a file rule.

Enable additional checks

perch scan --filter type=docs
perch scan --filter type=refactor

To choose the default types for your repository, use the map form of perch.yaml:

scan_types: [defect, security, lint, docs]
rules:
  - name: errors-reach-callers
    where: "src/**/*.py"
    each: method
    ensure: >-
      A failed operation reports the error to its caller.
      Catching an exception and returning a success-shaped
      default breaks this rule.

Markdown documentation checks are custom lint rules. The built-in docs type asks about methods and their documentation. See documentation rules for Markdown examples.

Filter saved findings

perch issues --filter type=security
perch issues --filter type=defect --min 80

issues filters results already saved locally. It makes no model requests and cannot add a scan type the previous run did not ask about.

Check a branch

With origin/main fetched, limit the scan to the branch’s changes:

perch scan --since origin/main --filter type=defect,security

Exit 3 means the run found a failing result. Exit 1 means it could not run, and 2 indicates an invalid command. Keep those outcomes distinct in CI.

The scan reference lists the built-in questions. Rule configuration covers scan_types, thresholds, and gates.