Command reference

Every command, its flags, the environment variables perch reads, and its exit codes.

The Perch command line interface (CLI) lets you scan code, review issues and manage rules from your terminal. Every command follows the same pattern:

perch <command> [options]

Commands that need a model endpoint use Perch Cloud by default. You can sign in with perch login, a CI token or a GitHub Actions OIDC token, or set PERCH_BASE_URL to use a different endpoint. See Environment.

Every command accepts --json, which prints the same information as JSON. Commands that read or write results accept --out DIR, which defaults to .perch. To see a command's options, run perch <command> --help. perch findings is another name for perch issues.

perch login#

perch login [organization-id]

Prints a link and a code to confirm in your browser, then saves the login to ~/.perch/cloud.json, outside the repository. If your account belongs to more than one organization, Perch lists them and asks you to run perch login <id> with the one you want.

perch logout#

perch logout

Removes the login saved on this device. To revoke a CI token, use the Perch Cloud dashboard.

perch scan#

perch scan [target] [options]

Parses the repository at HEAD with tree-sitter, then asks the model about each method with its callers and callees in view. Custom rules from perch.yaml and .perch/rules/ are asked at the same time. target is a file or directory to scan, and defaults to the current directory.

The scan exits with code 3 when it lists a problem. scan_types in perch.yaml sets which types of problem it asks about, and defaults to defect and lint.

With --since, Perch asks only about methods the diff touches. The bug questions has_bug, bug_edge_case, kind and severity go in a request that contains the method's code at the merge base with REF and the diff, without callers or callees. Custom rules and other types of question are asked in the usual request, with callers and callees.

perch coverage#

perch coverage [target] [options]

Runs your tests against small edits to your code, called mutants, and asks the model which surviving mutants a caller could notice. It lists those survivors, tests that catch nothing, and tests that catch exactly what another test catches. Test coverage explains the output and lists the supported test frameworks. It exits with code 3 when it lists a problem and 1 when it can't run your tests.

perch issues#

perch issues [issue-id] [options]

Lists open issues from the last scan, most serious first, 10 rows at a time. With an issue ID, it shows everything Perch recorded about that method. It reads .perch and sends no requests.

perch check#

perch check <path | path::method | issue-id> [options]

Checks a single method or file as it is on disk. For a method, Perch asks its built-in questions and every custom rule that applies to it. For a file, it asks the rules that apply to the file. perch check works on uncommitted code and doesn't save its results. It exits with code 3 if anything it checked is still broken.

perch rules#

perch rules [list | add <name> | edit <name> | remove <name>] [options]

Writes rules to perch.yaml, or to the file under .perch/rules/ that --file names, and keeps the file's comments and order. edit and remove find the file a rule is in. Most rules are a yes-or-no sentence, so --ensure is often the only flag you need:

perch rules add errors-reach-the-caller --each method --where "**/*.py" --ensure "When this method catches an exception, it raises it again or returns an error."

For a question whose answer isn't yes or no, use the longhand flags:

Semantic linting has an example of each kind of rule.

perch close#

perch close <issue-id>... [options]

Closes one or more issues, such as false positives or code you've reviewed and decided to keep. A closed issue stays closed through later scans and edits until you reopen it, and perch issues <id> shows the reason you gave. You can also close a problem reported by perch coverage by passing its ID.

perch reopen#

perch reopen <issue-id>... [options]

Puts closed issues back on the list. --kind reopens only some kinds of problem on an issue.

perch setup#

perch setup <claude-code | codex | pi | cursor> [options]

Installs the Perch skill for a coding assistant in the current repository:

It also adds Perch Cloud's MCP server, perch-cloud at https://dash.perchscan.com/mcp, to .mcp.json for Claude Code and .cursor/mcp.json for Cursor. For Codex, it prints the codex mcp add command to run. An existing perch-cloud entry is left as it is.

If the skill file matches the one this version of Perch ships, Perch changes nothing. If it differs, because you edited it or an older Perch wrote it, Perch leaves it alone and exits with code 2.

perch in a coding assistant lists what the skill tells the assistant to do.

perch ci#

perch ci [run-id] [options]

Lists this branch's CI runs in Perch Cloud, newest first, including runs still in progress:

$ perch ci
ID                                    Commit   Pull request  Result               When
043812ac-ea68-4c3b-88f0-737328f62826  5d7b033  #320          clean                23h ago
edf9f510-875c-44c8-8ff1-773e286be26e  a246d74  #320          clean                24h ago
6323adfc-9440-4640-badf-58c8e61cd5ba  d738e69  #320          4 problems, failing  45h ago

With a run ID, it shows that run's issues in the same layout as perch scan:

$ perch ci 6323adfc-9440-4640-badf-58c8e61cd5ba
docs/coverage.md
  ID        Line  Severity  Type  Confidence  Problem                   Method
  8fd1e766     1  -         lint         72%  docs-sentences-are-short  docs/coverage.md

src/coverage.js
  ID        Line  Severity  Type    Confidence  Problem             Method
  8d9306ba   428  P1        defect         71%  wrong_return_value  askCoverage.<anonymous>.build
  7a5c2d1b   463  P1        defect         68%  wrong_return_value  askCoverage.<anonymous>.build#2

test/test-detection.test.js
  ID        Line  Severity  Type  Confidence  Problem                     Method
  69903bef     1  -         lint         61%  tests-assert-real-behavior  test/test-detection.test.…

✖ 4 problems in 3 files, failing
#320 at d738e69, finished 45h ago: https://dash.perchscan.com/#/scan/6323adfc-9440-4640-badf-58c8e61cd5ba

On a pull request, each issue also shows the state of Perch's review comment on it: open, fixed when a later scan stopped reporting it, or resolved once someone resolves the thread. Replies are listed underneath. With --json, each issue's method works as a perch check target.

perch ci uses your perch login and the repository named by the origin remote. A CI token in PERCH_API_KEY also works, but sees only its own repository's finished runs. With a run ID, it exits with the run's result: 3 if the run found failing issues, and 1 if the run didn't finish.

perch cloud#

perch cloud [set] [options]

Shows your account, your workspace, and this repository's pull request settings in Perch Cloud: whether the GitHub app is installed, whether pull requests are scanned, which types of problem are asked about, whether Perch reads the changed code or the whole repository, and whether issues fail the Perch Scan check. The repository is the one the origin remote names.

perch cloud set changes the settings you pass and leaves the rest. It needs a workspace admin signed in with perch login. A CI token can't read or change settings.

perch doctor#

perch doctor [options]

Checks that Perch can run here: Node, credentials, git, the repository and commit, the results directory, and whether perch.yaml parses. A failed check says how to fix it, and the command exits with code 1.

Below that, it reports on the last run: every method it couldn't read and the error, every question it asked and what each one raised, and the end of .perch/scan.log if the run didn't finish. The report contains names, paths, counts and error messages but no source code, so you can paste it into a bug report.

Environment#

Perch sends scan, coverage and check requests to Perch Cloud unless PERCH_BASE_URL names another endpoint. Without PERCH_BASE_URL, it signs in to Perch Cloud with the first of these it finds: a CI token in PERCH_API_KEY, the login saved by perch login, or a GitHub Actions job's OIDC token when the job has id-token: write.

Perch uses PERCH_BASE_URL exactly as given, including its path, query string and any trailing slash. To use TypeSafe System One:

export PERCH_BASE_URL=https://api.typesafe.ai/v1/systemone
export PERCH_API_KEY='paste-your-TypeSafe-key-here'

To use a Liquid AI decision model, which uses the same request format:

export PERCH_BASE_URL=https://api.liquid.ai/decisions/v1/systemone
export PERCH_API_KEY='paste-your-Liquid-key-here'
export PERCH_MODEL_ID=d1:free

To use OpenAI's Decisions API:

export PERCH_BASE_URL=https://api.openai.com/v1/decisions
export OPENAI_API_KEY='paste-your-OpenAI-key-here'

Perch translates its questions and answers to and from the Decisions API format when the URL's path ends in /decisions.

Any other endpoint must accept the System One format, where typed questions about a piece of code are answered with probabilities. An OpenAI-compatible chat endpoint does not accept it.

Models accept different numbers of questions in one request. If a model reports max_questions in its answers, Perch keeps its first request to eight questions and sizes later requests to fit. For a model that reports nothing, set PERCH_MAX_QUESTIONS.

How much code goes in one request also depends on the model: about 24k tokens of a method and its neighbours for Jev, whose requests take 64k, and about 200k for OpenAI's Decisions API and for Perch Cloud. Any other model gets Jev's budget. PERCH_CONTEXT_LENGTH sets the size of one request yourself; the code gets 80% of it, and the code plus any one question 96%. A context length past 64k on TypeSafe sends the TypeSafe-Danger-Zone-Long-Context header, which raises Jev's limits to 262k. TypeSafe says that is slower and less accurate, so Perch never turns it on unless you set the length.

Configuration file#

~/.perch/config.toml sets defaults for this machine. It accepts four settings, each a quoted string:

organization = "your-organization-id"
repository = "your-repository-id"
base_url = "https://api.typesafe.ai/v1/systemone"
model = "jev-latest"

They set PERCH_ORGANIZATION, PERCH_REPOSITORY, PERCH_BASE_URL and PERCH_MODEL_ID. An environment variable overrides the file.

Exit codes#

A scan asks about defects and custom rules unless scan_types in perch.yaml lists other types, and any problem it lists makes it exit with 3. A rule with gate: false is still listed, but doesn't change the exit code.