> For the complete documentation index, see [llms.txt](https://docs.codna.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codna.ai/reference/cli.md). # CLI Reference `codna` is the single command you run to understand, fix, and secure a repository. Reach for it when you want to map an unfamiliar codebase, turn a failing test into a patch (or a pull request), or prove which scanner findings are actually reachable before anyone wastes time on them. Every subcommand drives the packaged Codna runtime locally. Repository intelligence runs in-process through the bundled Algenta SDK/core, Telys ships inside the Codna package, and local step state is written to local files under the runtime root. ## Global behavior Credentials come from the environment or the OS keychain. ```bash export CODNA_API_KEY="your-codna-key" export OPENAI_API_KEY="your-provider-key" # or ANTHROPIC_API_KEY / GEMINI_API_KEY ``` When verified planning needs model execution, Codna starts or reuses the packaged sidecar-only agent core on `127.0.0.1:18601`. | Variable | Default | Meaning | | --------------------------------------------------------- | ------- | ------------------------------------------------ | | `CODNA_API_KEY` | (none) | Codna license / metering key. | | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | (none) | Provider key for model-backed fixes and reviews. | A few rules apply to every command: * **`repo` argument.** Most commands take an optional positional `repo`. It defaults to `.` (the current directory). * **Local path vs git URL.** If `repo` resolves to an existing directory on this machine, Codna registers it as a `local_repo` connector and the local SDK/core reads it directly. If `repo` starts with `http://`/`https://` or ends in `.git`, it is registered as a `github_repo` connector. Anything else is rejected with `'': not a local directory or a git URL.` * **Global flags.** `codna --version` prints the installed version. `codna --config PATH` points at a specific config file (default: `./codna.yaml` or `./.codna.yaml`). Running `codna` with no subcommand prints help and exits `0`. * **JSON output.** Most commands accept `--json` to emit a machine-readable result instead of text. * **Exit behavior.** On success a command exits `0`. Any fatal error is printed to stderr and exits `1`. See [Exit codes and errors](#exit-codes-and-errors). ```bash codna --version codna # prints help, exits 0 ``` {% hint style="info" %} By default `codna` runs the engine in-process, so no separate engine service is required. If you set a remote engine URL without a key, the run fails with the message `no API key — set CODNA_API_KEY (your codna key).` — emitted in the `message` field of the JSON error described under [Exit codes and errors](#exit-codes-and-errors). {% endhint %} ## Commands Pick a tab for the command you want. Each tab carries that command's synopsis, full options table, and examples. {% tabs %} {% tab title="triage" icon="magnifying-glass" %} Understand a repository and locate the code relevant to an issue. It is fast and deterministic, and it spends no time generating a patch — useful on its own to orient yourself, or as the first step before a fix. ``` codna triage [repo] [--ref REF] [--issue TEXT] ``` | Flag | Value | Default | Meaning | | --------- | --------------------- | -------------------------------------------------------- | ---------------------------------------------------------- | | `repo` | local path or git URL | `.` | Repository to snapshot. | | `--ref` | branch/tag/commit | repo default | Specific ref to snapshot. | | `--issue` | text | `Map this repository and locate its most relevant code.` | What you are looking for; steers which files are surfaced. | What it does: registers the repo, takes a snapshot, runs `triage_repository`, and prints the suspect files plus the context reduction (raw repository tokens versus the evidence bundle handed to the agent). ```bash # Just map the repo (no issue text) codna triage . # Point it at a symptom codna triage . --issue "checkout total is wrong when a coupon is applied" # A specific branch of a remote codna triage https://github.com/acme/shop.git --ref release/2.3 \ --issue "intermittent 500 on /orders" ``` What you'll see: ``` codna: understanding . … ✓ codna understood 1843 files in 6.2s suspect files : src/checkout/coupon.py, src/checkout/total.py context : 2,910,442 → 18,000 tokens (162× smaller for the agent) ``` The `context` line is only printed when the engine returns a reduction ratio. If no suspect files are found, the line reads `suspect files : (none)`. {% endtab %} {% tab title="fix" icon="wrench" %} Find and fix a bug. `codna fix` triages the repository, builds a decision plan, and produces a patch. 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 gate (a simulation) before anything is applied. ``` codna fix [repo] (--issue TEXT | --from-junit FILE | --failing-test ID... | --tests) [--test-cmd CMD] [--ref REF] [--model MODEL] [--max-iterations N] [--apply | --open-pr] [--github-token TOKEN] [--base-branch BRANCH] [--pr-title TITLE] [--pr-body BODY] [--json] ``` | Flag | Value | Default | Meaning | | -------------- | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repo` | local path or git URL | `.` | Repository to fix. | | `--issue` | text | (none) | What is broken. Required unless a test source (`--failing-test`, `--from-junit`, or `--tests`) supplies failing tests. If both are given, `--issue` wins. | | `--from-junit` | path | (none) | Read failing tests from a JUnit/pytest XML report; derives the issue text and the failing-test list. | | `--tests` | flag | off | Auto-discover failing tests by running the repo's tests (sandboxed) and fix them. | | `--apply` | flag | off | Apply the patch to a new local branch. | | `--open-pr` | flag | off | Push a branch and open a pull request. Requires a git URL and a write token. |
Advanced flags | Flag | Value | Default | Meaning | | ------------------ | -------------------- | -------------------------------- | ------------------------------------------------------------------------------------- | | `--failing-test` | test id (repeatable) | `[]` | Failing test ids passed to the planner as signals. | | `--test-cmd` | command | `pytest` | Custom test command for `--tests`; writes JUnit to `$CODNA_JUNIT`. | | `--max-iterations` | integer | `1` | With `--tests --apply`, re-fix up to N times until the tests pass. | | `--ref` | branch/tag/commit | repo default | Specific ref to snapshot. | | `--model` | planner model | `repository.verified_agentic_v1` | Planner model used to build the decision plan. | | `--github-token` | token | env | Write token for `--open-pr`. Falls back to `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. | | `--base-branch` | branch | repo default | Pull request base branch. | | `--pr-title` | text | `codna: fix ` | Pull request title. | | `--pr-body` | text | generated summary | Pull request body. | | `--json` | flag | off | Emit the fix result as JSON. |
### Supplying the issue `codna fix` needs to know what's broken. Provide it directly with `--issue`, let Codna auto-discover with `--tests`, or read a test report with `--from-junit` (every `` with a `` or `` is collected). If none supplies a failing test, it exits 1 with this JSON error on stderr: ```json { "error": { "code": "cli_error", "message": "`codna fix` needs --issue (or --from-junit / --tests) describing what's broken.", "details": {} } } ``` ### Examples ```bash # 1) Diagnose only — print the patch reference, write nothing codna fix . --issue "NullPointerException in OrderService.total()" # 2) Drive it from a test report and apply to a local branch codna fix . --from-junit reports/junit.xml --apply # 3) Repeatable explicit failing tests codna fix . --issue "coupon math" \ --failing-test tests/checkout/test_total.py::test_coupon \ --failing-test tests/checkout/test_total.py::test_stacking # 4) Open a pull request against a remote export GITHUB_TOKEN="ghp_…" codna fix https://github.com/acme/shop.git \ --issue "coupon double-discount" --open-pr \ --pr-title "Fix coupon double-discount" --base-branch main ``` What you'll see (diagnose-only): ``` codna: fixing . … ✓ codna fixed . in 41s root cause : total() applies the coupon twice when stacking is enabled symbol : OrderService.total (blast radius: 3) confidence : 86% · regression risk: 4% context : 2,910,442 → 18,000 tokens (162× smaller) agent : verified_agentic_v1 via codna · cost: $0.214 patch : patch://snap-9f2/abc123 (--apply for a local branch · --open-pr to open a PR) ``` What you'll see (`--open-pr`): ``` ✓ opened pull request: https://github.com/acme/shop/pull/482 ``` What you'll see (`--apply`): ``` applied : branch codna/fix-coupon-double-discount @ /tmp/codna-checkout/abc123 ``` If the apply step fails, Codna does not abort the run; it prints the error and the patch ref so you can recover: ``` apply failed : (patch ref: patch://snap-9f2/abc123) ``` {% hint style="warning" %} `--open-pr` requires a git URL — a local path has no remote to push to — and a write-scoped token. With a local path the error message is `--open-pr needs a git URL (a local path has no remote to push to).`; without a token, `--open-pr needs a write token: pass --github-token or set GITHUB_TOKEN.` {% endhint %} ### End-to-end: failing CI to a pull request {% stepper %} {% step %} #### Set credentials ```bash export CODNA_API_KEY="your-codna-key" export GITHUB_TOKEN="ghp_write_scoped_token" ``` {% endstep %} {% step %} #### Reproduce locally and capture a JUnit report ```bash pytest --junitxml=reports/junit.xml || true ``` {% endstep %} {% step %} #### Have Codna read the report and open a PR on the remote ```bash codna fix https://github.com/acme/shop.git \ --from-junit reports/junit.xml \ --ref main \ --open-pr \ --base-branch main ``` {% endstep %} {% step %} #### Review and merge Codna prints the PR URL; review and merge as usual. {% endstep %} {% endstepper %} {% endtab %} {% tab title="review" icon="magnifying-glass-plus" %} Review a pull request read-only and post high-confidence inline findings (correctness, security, performance) anchored to the changed lines, plus a non-blocking "Codna Review" check. Each finding invites `@codna fix`, which routes it into the verified-fix workflow. See [Codna Review](/guides/review.md) for the full feature. ``` codna review [repo] [--pr PR] [--post] [--github-token TOKEN] [--diff RANGE | --base REF] [--min-confidence N] [--max-findings N] [--effort low|medium|high] [--full] [--blocking] [--model MODEL] [--json] ``` | Flag | Value | Default | Meaning | | ------------------- | ------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------- | | `repo` | local path | `.` | Repository whose diff to review. | | `--pr` | `123`, `owner/repo#123`, or a PR URL | (none) | PR to review and, with `--post`, comment on. | | `--post` | flag | off | Post one review + the "Codna Review" check. Needs `--pr` and a write token. | | `--diff` / `--base` | diff range / ref | `HEAD` | What to review (e.g. `origin/main...HEAD`). | | `--min-confidence` | 0–1 | `0.75` (or `codna.yaml`) | Only report findings at or above this confidence. | | `--max-findings` | integer | `10` (or `codna.yaml`) | Cap the number of findings. | | `--effort` | `low` \| `medium` \| `high` | `medium` | Review depth — higher is more thorough (more agent iterations, more cost). | | `--full` | flag | off | Review the whole PR, not only commits since Codna's last review. | | `--blocking` | flag | off | Fail the check on a blocking-severity finding (default: non-blocking). | | `--github-token` | token | env | Write token for `--post`. Falls back to `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. | ```bash # review the working changes codna review . # review only what changed vs main codna review . --diff origin/main...HEAD # review a PR and post the findings + check (needs a write token) codna review --pr owner/repo#123 --post --effort high ``` The review is read-only: it never runs your code, applies a patch, or holds a `contents: write` token. {% endtab %} {% tab title="secure" icon="shield-halved" %} Ingest a scanner's SARIF, prove which findings are reachable/exploitable, and report which are autofix-eligible. Classification is read-only and uses zero LLM 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 reachable finding through the privilege-separated writer. ``` codna secure [repo] --from-sarif FILE [--ref REF] [--engine local|remote] [--verification FILE] [--fix | --open-pr] [--github-token TOKEN] [--base-branch BRANCH] [--repo-slug OWNER/REPO] [--evidence-dir DIR] ``` | Flag | Value | Default | Meaning | | ---------------- | --------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repo` | local path or git URL | `.` | Repository to analyze. `--fix`/`--open-pr` need a local checkout. | | `--from-sarif` | path | (required) | Scanner SARIF output (CodeQL/Semgrep/Snyk/Trivy). | | `--engine` | `local` \| `remote` | `local` | Reachability engine. `local` is the packaged bounded self-host reference and never claims `exploitable`; `remote` is an explicit advanced engine override. | | `--verification` | path | (none) | `codna-security.yaml` manifest pinning the scanner and build/test commands. Required for `--open-pr`; required for `--fix` unless `--engine local`. | | `--fix` | flag | off | Remediate eligible findings; opens no PR. The default `--engine local` applies the verified patch to your checkout (re-verified there); `--engine remote` without `--open-pr` is report-only. | | `--open-pr` | flag | off | Open a fix PR per reachable finding. Requires a resolved manifest and a write token. |
Advanced flags | Flag | Value | Default | Meaning | | ---------------- | ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--ref` | branch/tag/commit | repo default | Specific ref to snapshot. | | `--github-token` | token | env | Write token for `--open-pr`. Falls back to `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. | | `--base-branch` | branch | `main` | Pull request base branch. | | `--repo-slug` | `owner/repo` | derived from git remote | Target repo for `--open-pr`. | | `--evidence-dir` | path | (none) | Write signed evidence bundles for the `secure-open-pr` handoff. Requires `--fix`, `--engine remote`, `--verification`, and `CODNA_ATTESTATION_KEY`; not combinable with `--open-pr`. |
Classification-only run: ```bash codna secure . --from-sarif results.sarif ``` What you'll see: ``` codna: understanding . for security analysis … ✓ analyzed 7 finding(s) from results.sarif → [reachable] js/sql-injection (taint) autofix-eligible · [unreachable] py/weak-hash (config) no reachable path from an entry point → [reachable] js/xss (taint) autofix-eligible summary: reachable=2, unreachable=5 · autofix-eligible: 2 ``` A scanner-less local fix (report-only, proves the fix but opens no PR): ```bash codna secure . --from-sarif results.sarif --engine local --fix ``` {% hint style="info" %} The full security workflow — SARIF provenance, the `codna-security.yaml` verification manifest, the sandboxed worker, attestations, and the privilege-separated PR writer — is documented in depth on the Security Autofix page. This section is a CLI summary only. {% endhint %} Guard rails enforced before any work begins (each raises a `cli_error` whose `message` reads): * `--from-sarif` is mandatory — `codna secure needs --from-sarif .` * `--open-pr` requires `--verification` — `--open-pr needs --verification …` * `--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.` {% endtab %} {% tab title="secure-open-pr" icon="file-signature" %} 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. This command is normally invoked by the Codna GitHub Action rather than by hand. ``` codna secure-open-pr --evidence DIR --repo-slug OWNER/REPO [--github-token TOKEN] [--base-branch BRANCH] ``` | Flag | Value | Default | Meaning | | ---------------- | ------------ | ---------- | ----------------------------------------------------------------------------------- | | `--evidence` | dir | (required) | Evidence directory containing `attestation.json`, `patch.diff`, and `finding.json`. | | `--repo-slug` | `owner/repo` | (required) | Target repository. | | `--github-token` | token | env | Write token. Falls back to `GITHUB_TOKEN`. | | `--base-branch` | branch | `main` | Pull request base branch. | It also requires `CODNA_ATTESTATION_KEY` in the environment — the same key the worker used to sign the bundle — to verify the attestation. ```bash export CODNA_ATTESTATION_KEY="shared-with-the-worker" export GITHUB_TOKEN="ghp_write_scoped_token" codna secure-open-pr --evidence ./evidence --repo-slug acme/shop --base-branch main ``` What you'll see: ``` ✓ opened draft PR: https://github.com/acme/shop/pull/507 ``` Common failure messages (the `message` field of the JSON error on stderr): ``` evidence is missing finding.json (cannot derive the branch). set CODNA_ATTESTATION_KEY (shared with the worker) to verify the attestation. secure-open-pr needs a write token: --github-token or $GITHUB_TOKEN. secure-open-pr needs --repo-slug owner/repo. writer refused to open the PR: ``` {% hint style="warning" %} `CODNA_ATTESTATION_KEY` must match the key the worker used, otherwise the attestation cannot be verified and no PR is opened. See the Security Autofix page for the end-to-end two-job flow. {% endhint %} {% endtab %} {% tab title="mcp" icon="plug" %} Run codna as an MCP (Model Context Protocol) server, or install it into a client such as Cursor or Claude Desktop. ``` codna mcp [start|install] [--repo REPO] [--client cursor|claude] [--project] ``` | Flag | Value | Default | Meaning | | ----------- | --------------------- | ----------- | ------------------------------------------------------------------------- | | `action` | `start` \| `install` | `start` | Serve over stdio, or write the config into a client. | | `--repo` | local path or git URL | `.` | Default repo for MCP tools that accept one. | | `--client` | `cursor` \| `claude` | (none) | For `install`: which client to configure. | | `--project` | flag | user config | For `install`: write the project-local config instead of the user config. | `codna mcp` serves over stdio; `codna mcp install --client cursor` writes the client config for you. It uses the same packaged runtime and keys as every other command. See [MCP Server](/guides/mcp.md) for the tool list and client snippets. {% endtab %} {% tab title="impact" icon="list-check" %} Repo-aware test selection: prints the tests a diff can actually affect, so CI runs the subset instead of the full suite. Multi-language classification (any language Codna extracts), precise Python import-graph edges, and a run-MORE-never-fewer bias: broad/config changes, unclassifiable files, and shared-core changes print `ALL`. Deterministic and offline — no engine, no tokens. ``` codna impact [--repo PATH] [--base REF] [--head REF] [--changed FILE ...] [--shared-core-fraction N] [--json] ``` | Flag | Value | Default | Meaning | | ------------------------ | ---------- | ---------------------- | ----------------------------------------------- | | `--repo` | local path | `.` | Repository root to analyze. | | `--base` / `--head` | git refs | `origin/main` / `HEAD` | The diff to analyze (`base...head`). | | `--changed` | file list | (none) | Explicit changed files; skips git entirely. | | `--shared-core-fraction` | 0–1 | `0.34` | Affected-share above which the full suite runs. | | `--json` | flag | off | Emit `{"mode", "tests", "reason"}`. | Output contract for CI consumers: one test path per line on stdout (empty subset = print nothing), the reason on stderr, or the sentinel `ALL` when the full suite must run. ```bash # What should run for the current branch vs origin/main? codna impact # CI wiring (explicit diff, machine-readable) codna impact --repo . --changed apps/web/App.tsx --json ``` {% endtab %} {% tab title="memory" icon="database" %} Codna code memory: the repo indexed as structural units into an on-device Telys collection. `codna memory export` writes it as an ultra-small READ-ONLY serve artifact (quantized int8 slab + provenance — about 4x smaller than the full index) that any device can open with Telys' `open_compact`. Indexes first when the memory is empty, refreshes when stale, all in the one command. ``` codna memory export PATH [--mode int8|pq] [--repo REPO] ``` | Flag | Value | Default | Meaning | | -------- | -------------- | ---------- | ------------------------------------------------------------------- | | `PATH` | directory | (required) | Where to write the artifact. | | `--mode` | `int8` \| `pq` | `int8` | Quantization tier; `pq` is the super-large-repo tier (needs faiss). | | `--repo` | local path | `.` | Repository to index. | ```bash # Ship this repo's code memory as one compact directory codna memory export ./dist/repo-memory ``` Requires a Telys carrying the compact seam; older Telys fails with upgrade guidance instead of writing a bad artifact. {% endtab %} {% endtabs %} ## Operational commands Setup and runtime commands. Each links to its detailed page. | Command | Synopsis | Purpose | | -------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `codna login` | `codna login [--token TOK] [--plan PLAN] [--no-browser] [--no-install]` | Authorize this device for on-device memory. See [Code Memory](/concepts/memory.md). | | `codna init` | `codna init [--force] [--no-agents]` | Scaffold `codna.yaml` (and `AGENTS.md`) in the current directory. | | `codna key` | `codna key {set [--stdin] \| list \| rm }` | Manage the on-device provider key in the OS keychain. See [Models & BYOK](/concepts/models-and-byok.md). | | `codna status` | `codna status` | Concise health: engine · telys · keys. See [Operations](/reference/operations.md). | | `codna doctor` | `codna doctor [--start-stack \| --stop-stack]` | Inspect the local runtime and start/stop the sidecar. See [Operations](/reference/operations.md). | ## Exit codes and errors On success a command exits `0`. On a fatal error it prints a JSON object to stderr and exits `1`: ```json { "error": { "code": "cli_error", "message": "…", "details": {} } } ``` Some commands use the exit code to signal a result, not just a crash: | Command | Exit `1` when | | -------------- | ------------------------------------------------------------------------------------- | | `fix` | Verification ran and did not reach green (`verified: false`). | | `review` | A blocking-severity finding failed the `Codna Review` check (only with `--blocking`). | | `secure --fix` | A requested eligible fix did not verify. | | `key` | A keystore error (`2` on a usage error). | | `login` | Onboarding failed. | ## Troubleshooting See [Troubleshooting](/reference/troubleshooting.md) for every error message and its one-line fix. Fatal errors are emitted as JSON on stderr (`{"error": {"code", "message", "details"}}`); the `message` field carries the text and names the fix. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.codna.ai/reference/cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.