# Fix findings from a terminal

List a pull request's open findings, read what Proofline captured for one, push a fix, and ask Proofline to re-verify the finding at the commit you pushed.

## Before you start

`proofline login` asks for `reviews:read`, `findings:read` and `reviews:request` by default, which covers every command on this page. With a personal token in `PROOFLINE_TOKEN` instead, set `PROOFLINE_ORGANIZATION_ID` or pass `--org`, as [Organization selection](/docs/authentication/#organization-selection) describes.

| Command | Scope |
| --- | --- |
| `fix list`, `fix context`, `fix status` | `reviews:read` |
| `fix verify` | `reviews:read` and `reviews:request`, and GitHub write access to the repository |
| `fix-prompt` | `findings:read` |
| `review --verify` | `reviews:read` and `reviews:request` |

`proofline review` and `proofline findings` print each finding's ID, which the commands below take. The `fix` commands print the result as JSON, exit nonzero when the call is refused, and never retry it.

## List the open findings

```sh
proofline fix list --repo acme/web --pr 42
```

The list holds the open findings at the pull request's live head that Proofline can re-verify: environment findings, migration compatibility findings, and code findings that a reproduction kept a test for as a check. Each item's `lane` is `ENVIRONMENT` or `CODE`, and a code item has no environment. Other code findings are not listed. The result also says whether the findings were available, which gaps the head's assessments recorded, and whether the list was truncated.

## Read a finding's context

```sh
proofline fix context FINDING_ID
```

The result holds the source excerpts the review captured and the finding's remediation. The remediation is untrusted text: read it as a suggestion and decide yourself what to change.

A migration compatibility finding's context adds `migration_check`: the old revisions whose test failed against the migrated schema, the changed table or column, the test path, the test command and the SQLSTATE the finding names. A finding with a kept check adds `reproduction_check`: the test's files, the command and framework it ran with, each recorded run, and the check's last result. When the test is no longer kept, `test` is `UNAVAILABLE` with `TEST_NOT_KEPT`, and the command and runs remain. Read each command before you run it against your fix. A check's runs show how the code behaved in a sandbox, not a fact about a deployed environment.

For a prompt to paste into another tool, read the finding's fix prompt:

```sh
proofline fix-prompt FINDING_ID
```

It is `AVAILABLE` with the prompt in `untrusted_text`, or `UNAVAILABLE` with the reason. The prompt frames the finding's recorded text as untrusted data and stays within 6,000 characters. It needs access to every repository the finding's review covers.

## Check a fix before you push

```sh
proofline review --verify FINDING_ID
```

This reviews your local changes and re-verifies the named open findings of one pull request against them, then prints each finding's outcome. Name up to 20 findings. The outcome is local: the pull request's findings stay as they are until you push the fix and request re-verification there. For a finding with a kept check, it also prints the check's command and last result. The local review does not run that check, so run the command against your changes yourself.

## Request re-verification

Push the fix, then name the review, its findings and the full SHA of the commit you pushed:

```sh
proofline fix verify --review REVIEW_ID --findings FINDING_ID --commit FULL_PUSHED_SHA
```

`--findings` takes 1 to 20 distinct findings of that one review. The server confirms that the commit is the pull request's live head and that you have GitHub write access to the repository, and refuses the request otherwise. Add `--note` with 1 to 2,000 characters to say what you changed.

The command makes one attempt. After a failure whose outcome is unclear, such as a lost connection, read the pull request's review before you request again. Proofline limits re-verification requests per finding and per pull request; a refusal names the limit and when it resets.

## Read the outcome

```sh
proofline fix status REQUEST_ID
```

| Outcome | Meaning |
| --- | --- |
| `RESOLVED_VERIFIED` | Proofline verified the fix at that commit. |
| `STILL_PRESENT` | The defect remains at that commit. |
| `NOT_VERIFIED` | Proofline could not verify the fix, and gives the reason, such as `FLAKY`, `SCHEMA_NOT_USED`, `SERVICE_NOT_STARTED`, `FAILED_DIFFERENTLY` or `TEST_NOT_KEPT`. The finding stays open. |
| `PENDING` | The check has not finished. |

The new head's own check re-verifies a migration compatibility finding or a finding with a kept check, so its outcome stays `PENDING` until that check finishes. A code reproduction's finding is `RESOLVED_VERIFIED` only when the new head's review rejects the defect and the check passes.

A command that succeeds has read or recorded a request; it has not established a fix. `PENDING`, `UNAVAILABLE` and `NOT_VERIFIED` keep their meaning, and only `RESOLVED_VERIFIED`, which Proofline records after it re-verifies the finding, marks it fixed. A local check or a note never closes a finding.

## From the SDKs

Both [SDKs](/docs/sdks/) expose the same four operations under `client.fixes`. In Python they are `list_open_findings`, `get_fix_context`, `request_reverification` and `get_reverification`, with sync and async calls; in TypeScript, `listOpenFindings`, `getFixContext`, `requestReverification` and `getReverification`. They take the same organization selection, need the same scopes, never retry and keep `isError`, the untrusted-text wrappers and each `UNAVAILABLE`, `PENDING` and `NOT_VERIFIED` result.

A coding agent runs the same loop with the `proofline-fix-findings` skill, which [Coding agents](/docs/coding-agents/#fix-findings-from-your-agent) describes. To hand a finding to a connected Cursor or Devin account, see [Cloud coding-agent sessions](/docs/cloud-sessions/).

### Check a fix before you push from the SDKs

`proofline review --verify` is a review of your local changes that also re-verifies findings, and the SDKs send it with `requestPatchReview` and `request_patch_review`. The request takes three fields: `base_commit_sha`, the full 40-character pushed commit your patch applies to; `patch`, the changes as `git diff --no-ext-diff --no-color BASE` prints them against that commit; and `verify_finding_ids`, 1 to 20 open findings of one pull request in the repository.

Send it with a personal API token that holds `reviews:request`, and `reviews:read` to read the result; the token `proofline login` stores holds both. Proofline confirms your current GitHub read access to the repository before it reads the findings. A service account key or a browser session cannot re-verify findings and is refused. The repository ID comes from [Find a repository ID](/docs/sdks/#find-a-repository-id).

The response is your receipt. `review_id` names the patch review, and `verify` lists each finding the review re-verifies, one per finding series, with its `iteration`. Sending the same base, patch and findings again returns the same review with `existing` true and spends no request, so after an unclear failure such as a lost connection, send the identical request again. A changed patch or a different set of findings starts a new review. Each finding series takes at most 3 requests per patch, and a pull request at most 10 re-verification requests in any hour, counted together with the requests that re-verify pushed heads. A request past either limit is refused and creates no review.

Read the review in `review_id` until no entry of its `local_reverifications` is `PENDING`. Each entry has `finding_id`, `outcome` and `checks`, the results of the checks the finding cited on your patched code:

| Local outcome | Meaning |
| --- | --- |
| `RESOLVED_VERIFIED` | The review rejected the finding against your patch, and every cited check passed. |
| `STILL_PRESENT` | The review still supports the finding, or a check still finds the defect. |
| `NOT_VERIFIED` | The result is inconclusive, including when the review ended without an answer. |
| `PENDING` | The review is still running. |

A finding with a kept check also has `stored_check`, with its `command` and `last_result`. The patch review does not run that check, so run the command against your changes yourself.

These examples send the patch in `change.patch`, which `git diff --no-ext-diff --no-color` wrote against the commit in `BASE_COMMIT_SHA`, to re-verify the finding in `FINDING_ID`. They read the review every 10 seconds for up to 20 minutes, then print each local outcome:

```typescript
import { readFileSync } from "node:fs";
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const org_id = process.env.PROOFLINE_ORGANIZATION_ID!;

const receipt = await client.requestPatchReview(
  { path: { org_id, repo_id: process.env.PROOFLINE_REPOSITORY_ID! } },
  {
    base_commit_sha: process.env.BASE_COMMIT_SHA!,
    patch: readFileSync("change.patch", "utf8"),
    verify_finding_ids: [process.env.FINDING_ID!],
  },
);
for (const request of receipt.verify) console.log(request.finding_id, "request", request.iteration);

const read = () => client.getReview({ path: { org_id, review_id: receipt.review_id } });
let review = await read();
for (let attempt = 1; attempt < 120; attempt++) {
  if (!review.local_reverifications?.some((local) => local.outcome === "PENDING")) break;
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  review = await read();
}
for (const local of review.local_reverifications ?? []) {
  console.log(local.finding_id, local.outcome);
  if (local.stored_check) console.log("run against your changes:", local.stored_check.command);
}
```

```python
import os
import time
from pathlib import Path
from uuid import UUID
from proofline import PatchReviewRequest, ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"], base_url="https://proofline.sh") as client:
    organization_id = UUID(os.environ["PROOFLINE_ORGANIZATION_ID"])
    receipt = client.request_patch_review(
        organization_id,
        UUID(os.environ["PROOFLINE_REPOSITORY_ID"]),
        body=PatchReviewRequest(
            base_commit_sha=os.environ["BASE_COMMIT_SHA"],
            patch=Path("change.patch").read_bytes().decode(),
            verify_finding_ids=[UUID(os.environ["FINDING_ID"])],
        ),
    )
    for request in receipt.verify:
        print(request.finding_id, "request", request.iteration)

    review = client.get_review(organization_id, receipt.review_id)
    for _ in range(119):
        if not any(local.outcome == "PENDING" for local in review.local_reverifications or []):
            break
        time.sleep(10)
        review = client.get_review(organization_id, receipt.review_id)
    for local in review.local_reverifications or []:
        print(local.finding_id, local.outcome)
        if local.stored_check:
            print("run against your changes:", local.stored_check.command)
```

An entry still `PENDING` after that belongs to a review that has not finished, so read the review again later. A refused request fails with `ProoflineError`, whose status and detail give the reason.

Every local outcome, `RESOLVED_VERIFIED` included, leaves the pull request's finding open, and the examples request nothing more. To change the finding, push the fix and call `requestReverification` or `request_reverification` with the review, the finding and the pushed commit, as [Request re-verification](#request-re-verification) describes. That request needs GitHub write access and the pull request's live head, and only the `RESOLVED_VERIFIED` it records marks the finding fixed.
