CLI Reference

Understand a repository and locate the code relevant to an issue. It is deterministic, spends no model tokens, and generates no patch. Use it on its own to orient yourself, or as the first step before a fix.

What it does: snapshots the repository, maps it, and prints the suspect files plus the context reduction (raw repository tokens versus the evidence bundle handed to the agent).

What you will see. The values show the format; Codna prints the measured values for your repository:

The context line is printed only when a reduction ratio is available. If no suspect files are found, the line reads suspect files : (none).

Find and fix a bug. codna fix triages the repository, plans a patch, and reports the root cause. By default it prints the patch reference and stops; pass --apply to write a local branch, or --open-pr to open a pull request. Both write paths run the deterministic risk simulation before anything is applied.

Supplying the issue

codna fix needs to know what's broken. Provide it directly with --issue, let Codna discover failing tests with --tests, or read a test report with --from-junit (every <testcase> with a <failure> or <error> is collected). If none supplies a failing test, it exits 1 with this JSON error on stderr:

Verifying with your tests

--tests --apply is the verification loop: Codna runs the repository's tests in a sandbox, plans a patch, applies it to a local branch, re-runs the tests, and re-fixes up to --max-iterations times until they pass. The sandbox scrubs credentials and denies network access at the kernel level on Linux. The run ends with ✓ verified — tests pass after N attempt(s) in Ns or ✗ not fully green after N attempt(s): M test(s) still failing, and exits 1 in the second case.

--open-pr is one-shot: Codna plans, simulates, pushes and opens the pull request, then returns. Your CI runs the tests on the branch.

Examples

What you'll see (diagnose-only). The values show the format:

What you'll see (--open-pr):

What you'll see (--apply):

If the apply step fails, Codna does not abort the run; it prints the error and the patch reference so you can recover:

End-to-end: failing CI to a pull request

Review a change read-only and post high-confidence inline findings (correctness, security, performance) anchored to the changed lines, plus one codna review check. A clean diff at medium and high is posted as an Approve. See codna review for the verdict, the red-head note, and the registry check.

The review is read-only: it never runs your code, applies a patch, or holds a contents: write token.

Ingest a scanner's SARIF, prove which findings are reachable, and report which are autofix-eligible. Classification is read-only and uses zero model tokens. With --fix it applies the verified patch to your local checkout (re-verified there) but opens no PR; with --open-pr (which requires --engine remote) it opens a fix PR per eligible finding through the privilege-separated writer.

Classification-only run:

What you'll see:

The bracketed value is the verdict: exploitable, production-reachable, unreachable, or unknown. The default --engine local never prints exploitable.

A local fix (applies the verified patch to your checkout, opens no PR):

Guard rails enforced before any work begins (each raises a cli_error whose message reads):

• --from-sarif is mandatory — codna secure needs --from-sarif <results.sarif>.

• --open-pr requires --verification — --open-pr needs --verification <codna-security.yaml> …

• --fix on a non-local engine requires --verification (or switch to --engine local).

• SARIF with incomplete provenance is rejected — SARIF provenance incomplete: …

• --engine local --open-pr is refused — --open-pr needs the privilege-separated writer + a scoped token; --engine local --fix applies to the local checkout but opens no PR.

The writer half of the two-job security workflow. It verifies a worker's signed evidence bundle and opens the draft PR. It runs no repository code, so the write token lives only in this step. See GitHub Action § Security-proof flow for the two-job layout.

It also requires CODNA_ATTESTATION_KEY in the environment, the same key the worker used to sign the bundle, to verify the attestation.

What you'll see:

Common failure messages (the message field of the JSON error on stderr):

Run codna as an MCP (Model Context Protocol) server, or install it into a client such as Cursor or Claude Desktop. Needs the mcp extra: pip install "codna[mcp]".

codna mcp serves over stdio; codna mcp install --client cursor writes the client config for you. It exposes five tools: codna_triage, codna_fix, codna_secure, codna_recall, and codna_report_bug. See MCP Server.

Repo-aware test selection: prints the tests a diff can affect, so CI runs the subset instead of the full suite. Classification covers any language Codna extracts, with precise Python import-graph edges, and a run-more-never-fewer bias: broad or config changes, unclassifiable files, and shared-core changes print ALL. Deterministic and offline. No tokens.

Output contract for CI consumers: one test path per line on stdout (an empty subset prints nothing), the reason on stderr, or the sentinel ALL when the full suite must run.

Codna code memory: the repository indexed as structural units into an on-device collection. codna memory export writes it as a small read-only serve artifact, about 4x smaller than the full index, that any device can open. It indexes first when the memory is empty and refreshes when stale, all in the one command.

See Code Memory.

Keep a self-hosted runner fleet inside a chosen share of one machine. A job asks for a slot before it does real work and releases it when done. The gate never fails a build. See CI fleet gate.