Agent commands

The same commands a person runs. This page is what each returns in data, and what shows up in next.

Orientation

cf status --agent is the right first call. It answers whether the CLI works, whether the user is signed in, whether the provider is connected, and what is already scanned, in one round trip.

Call cf org list --agent second, before anything that writes. It tells you the slug to pass as --org and the role you hold there, which is what decides whether publishing or merging will be allowed at all. See Name the organization too.

The plan and the meter

cf plan --agent
cf plan upgrade pro --yearly --seats 3 --agent
cf plan portal --agent

data.usage reports the scan allowance, including percentUsed, remainingPercent, and exhausted in existing CLI clients. A rounded percentage cannot establish an exact remaining token count. Billing in the workspace shows the actual balance when available, along with the applicable refill date. Free does not refill; paid allowances refill monthly, including on yearly billing. Model tokens measure AI input and output, not dollars or a guaranteed number of scans. Read the current meter before starting new work. repositories, maxDepthRuns and canAdministerBilling describe limits and permissions.

Scanning

cf scan --repo acme/api --wait --agent
cf scan --repo acme/api --branch release/2.4 --wait --agent

--wait blocks until the scan settles, for up to about ten minutes, and returns status, findings, and error. Without it you get scanId immediately and have to poll cf status --agent yourself. Exit code 4 means the scan failed.

Listing findings

cf reproduced --repo acme/api --severity critical,high --agent
cf matched --repo acme/api --agent
cf reproduced --repo acme/api --category dependency --limit 20 --agent

data.findings arrives worst first. data.counts breaks the total down by wire severity. Each entry carries id, severity, severityLabel, title, file, line, category, cve, cwe, rule, description, guidance, matchedSources, and the state of any fix.

Reading one in full

cf reproduced show <finding-id> --repo acme/api --agent

Adds the vulnerable code, the data flow, the research that matched with its rationale, the references, and the patch if one exists. Read this before forming an opinion. In particular read dataflow: source and sink say how untrusted input reaches the dangerous call, steps walks the path, and ineffectiveSanitizers names guards that look protective and are not. That is what tells you whether a finding is reachable in practice.

Patching

cf fix generate <finding-id> --wait --agent
cf fix show <finding-id> --agent

Statuses are generating, ready, failed, skipped, publishing, opened, merged, and closed. The last two are reached once the pull request is resolved, and closed means it was closed without merging. When ready, data.fix.diff holds the unified diff, data.fix.explanation says why, and data.fix.file names the patch's primary file. A patch may change more than that one: read the diff for the full set rather than reporting file as the whole of it. For a dependency finding on a lockfile, the primary file is the manifest beside it rather than the lockfile itself, and for an npm lockfile the diff also carries the lockfile npm regenerated.

Proving

cf proof run <finding-id> --wait --agent
cf proof show <finding-id> --agent

data.proof.kind says what was checked: dependency-range, secret-rotation, exploit-replay, or none for a maintainability finding with no exploit. For exploit-replay the finding's reproduced attack is run in a sandbox against the code before and after the patch, with no model involved. data.proof.verdict says how it came out: proven, incomplete, refuted, or unprovable, and summary says why when it is not proven. A proof starts only when explicitly requested; opening a finding or generating a patch does not start one. Only refuted blocks publishing, with fix_proof_refuted, and the answer to it is to regenerate the patch.

Read data.proof.checks and data.proof.witness rather than quoting the verdict. attack-before and attack-after say what each run observed, and the witness holds the attack input and where it enters. A proof needs a patch to run against: without one it refuses with fix_not_found.

A proof that boots the app to attack it may need environment values to start. cf proof env --agent lists the names stored for the repository. cf proof env set <NAME> --stdin --agent stores one from stdin, and the value is never an argument. Ask the user before storing anything, and use test credentials only.

Publishing and merging

cf fix publish <finding-id> --yes --agent
cf fix merge <finding-id> --yes --agent

Publishing opens a real pull request. Merging lands code on the default branch. Both refuse with confirmation_required without --yes, and each is a separate decision: agreeing to open a pull request is not agreeing to merge it. --method merge|squash|rebase picks the strategy, squash by default.

If a pull request is already open you get {"alreadyOpen":true} with the existing URL, not a duplicate. Under --agent, always pass the finding id to cf fix merge: with none and no terminal to prompt in, it fails with usage_error.

Branches and history

cf branches --repo acme/api --agent
cf commits --repo acme/api --agent
cf reproduced --repo acme/api --scan <scan-id> --agent

cf branches gives every branch with the last scan of each: scanId, scanStatus, findings, scannedAt. A branch with no scanId has never been scanned, and asking for its findings answers branch_not_scanned rather than falling back to the default branch.

cf commits gives one row per scanned commit, newest first, with sha, message, author, committedAt, its scanId, and the deltas that scan produced: introduced, resolved, suppressed. That is the honest answer to when a vulnerability was introduced, because it is what reconciliation recorded rather than a diff you inferred.

Settings and exports

cf settings --repo acme/api --agent
cf settings mode push --repo acme/api --agent
cf settings depth max --repo acme/api --agent
cf settings checks sast,sca,secrets --repo acme/api --agent
cf sbom --repo acme/api --format cyclonedx --agent

Following next

The next array is computed from the state that was just fetched, so it already knows whether a fix exists and what the sensible following step is. Prefer it over commands you compose. It is also the cheapest way to stay correct when the CLI gains a step.

When a command comes back with ok: false, Errors and recovery lists every code, its exit code, and what to do about it. The scan and fix loop puts the commands on this page into the order a full cycle runs them in.

Working efficiently

• Start narrow. --severity critical,high on a large repository, then widen. A whole-repository listing is the biggest payload the CLI produces.
• Do not re-list to refresh one row. cf reproduced show <id> and cf fix show <id> are cheap and current.
• Batch the reading, serialise the writing. Read as many findings as you need, then generate patches one at a time so the user can judge each.
• Use `--exit-code` in CI, never string matching on output.