Fix findings from a terminal

View as Markdown

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 describes.

CommandScope
fix list, fix context, fix statusreviews:read
fix verifyreviews:read and reviews:request, and GitHub write access to the repository
fix-promptfindings:read
review --verifyreviews: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#

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#

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:

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#

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:

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#

proofline fix status REQUEST_ID
OutcomeMeaning
RESOLVED_VERIFIEDProofline verified the fix at that commit.
STILL_PRESENTThe defect remains at that commit.
NOT_VERIFIEDProofline 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.
PENDINGThe 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 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 describes. To hand a finding to a connected Cursor or Devin account, see Cloud coding-agent 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.

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 outcomeMeaning
RESOLVED_VERIFIEDThe review rejected the finding against your patch, and every cited check passed.
STILL_PRESENTThe review still supports the finding, or a check still finds the defect.
NOT_VERIFIEDThe result is inconclusive, including when the review ended without an answer.
PENDINGThe 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:

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);
}

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 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.