> 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/getting-started/quickstart.md). # Quickstart Install the Codna CLI, add a model key, triage a repository, and open an automated fix PR. Codna understands and fixes your repository from the command line. This page takes a clean machine from `pip install` to an open pull request: install, add a key, triage, then fix with `--open-pr`. {% hint style="info" %} Codna is the only thing you install. Repository understanding runs on your machine. There is no engine server to start or configure. {% endhint %} {% stepper %} {% step %} #### Install the CLI {% tabs %} {% tab title="pip" icon="python" %} ```bash pip install codna ``` This installs the `codna` command. It needs **no Node, Bun, Docker, or separate engine**. Add the MCP server later with `pip install "codna[mcp]"`. {% endtab %} {% tab title="from source" icon="code-branch" %} Install from a checkout, for development or to pin to a commit. The package lives in `cli/`: ```bash git clone https://github.com/thyn-ai/codna.git cd codna/cli pip install -e . ``` {% endtab %} {% endtabs %} Verify the install: ```bash codna --version ``` ``` codna 0.x.y ``` `codna --help` lists every subcommand: `triage`, `fix`, `review`, `secure`, `secure-open-pr`, `mcp`, `impact`, `memory`, `report`, `ci`, `init`, `doctor`, `status`, `login`, and `key`. {% endstep %} {% step %} #### Add a model key `codna fix` and `codna review` call your model provider. Store the provider key in the OS keychain. It is read through a hidden prompt, never passed on the command line, and never printed: ```bash codna key set anthropic # or openai, gemini, google, groq, mistral, openrouter, xai ``` Or export it for this shell: ```bash export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY, GEMINI_API_KEY, … ``` | Setting | Read from, in order | Needed for | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Model key | Environment variable, then the OS keychain (`codna key set`) | `fix`, `review` | | GitHub write token | `--github-token` flag, then `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN` | `fix --open-pr`, `review --post` | | Codna key | `codna login` (OS keychain) or `CODNA_API_KEY` | A remote engine, and executing any of the five MCP tools (`codna mcp`). Local CLI runs do not need it. | `codna triage` needs no key at all; the MCP tools all require the one-time free `codna login`. For the provider list and how to pin a model, see [Models & BYOK](/concepts/models-and-byok.md). {% endstep %} {% step %} #### Triage a repository `codna triage` maps a repository and locates the code most relevant to your problem. It is deterministic and spends no model tokens. ```bash codna triage [repo] [--ref REF] [--issue TEXT] [--json] ``` | Argument / flag | Meaning | Default | | ------------------- | ---------------------------------------------------------- | ----------------------------------------------- | | `repo` (positional) | Local path or git URL to understand | `.` (current directory) | | `--ref` | Branch, tag, or commit to snapshot | repo default | | `--issue` | Optional free-text description of what you are looking for | map the repo and surface its most relevant code | | `--json` | Emit the result as JSON | off | `repo` resolves the same way for every subcommand: an existing local directory is read directly; a string starting with `http://` or `https://`, or ending in `.git`, is fetched. Anything else is rejected. **Worked example:** ```bash codna triage . --issue "checkout total is wrong when a coupon is applied" ``` What you will see. The values show the format; Codna prints the measured values for your repository: ``` codna: understanding . … ✓ codna understood 1,284 files in 2.3s suspect files : src/checkout/total.py, src/pricing/coupon.py context : 6,200,000 → 18,400 tokens (337× smaller for the agent) ``` Field by field: | Line | What it means | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `codna: understanding . …` | The repo being snapshotted (echoes the `repo` argument). | | `✓ codna understood 1,284 files in 2.3s` | Total files in the snapshot and the wall-clock time to snapshot and triage. | | `suspect files` | The files triage ranked as most relevant to `--issue`. Prints `(none)` when there are no candidates. | | `context` | The raw repository token estimate, the focused evidence bundle the agent would consume, and the reduction ratio. | The `context` line appears **only** when a reduction ratio is available. If you omit `--issue`, Codna maps the repository against the default signal ("Map this repository and locate its most relevant code.") and still reports suspect files. To triage a remote repository at a specific commit: ```bash codna triage https://github.com/owner/repo.git --ref 9f3c1a2 --issue "intermittent 500 on /orders" ``` {% endstep %} {% step %} #### Open a fix PR `codna fix` triages the repository, plans a patch with the agent, and, when you ask it to write, runs a deterministic risk simulation before applying. With `--open-pr` it pushes a branch and opens a pull request. ```bash 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 | Meaning | Default | | ------------------- | --------------------------------------------------------------------------------- | --------------------------------- | | `repo` (positional) | Local path or git URL | `.` | | `--issue` | What is broken (free text). Required unless a test source supplies failing tests. | — | | `--from-junit` | Read failing tests from a JUnit/pytest XML report and derive the issue from them | — | | `--failing-test` | A failing test id; repeatable | — | | `--tests` | Run the repository's tests in a sandbox to discover failures, then fix them | off | | `--test-cmd` | Custom test command for `--tests` (writes JUnit to `$CODNA_JUNIT`) | pytest | | `--ref` | Branch, tag, or commit to snapshot | repo default | | `--model` | Planner model | `repository.verified_agentic_v1` | | `--max-iterations` | With `--tests --apply`, re-fix up to N times until the tests pass | 1 | | `--apply` | Apply the patch to a **local branch** (runs the risk simulation first) | off | | `--open-pr` | Push a branch and open a pull request (needs a git URL and a write token) | off | | `--github-token` | Write token for `--open-pr` (else `CODNA_GITHUB_TOKEN` / `GITHUB_TOKEN`) | — | | `--base-branch` | PR base branch | repo default | | `--pr-title` | Pull request title | `codna: fix ` | | `--pr-body` | Pull request body | generated summary (see below) | | `--json` | Emit the fix result as JSON | off | `--issue`, `--failing-test`, `--from-junit`, and `--tests` are how you tell Codna what to fix. If you pass none of them (and any JUnit report contains no failures), the command exits with an error. If you pass both `--issue` and a test source, `--issue` wins as the issue text while the failing tests are still passed through as signals. Choose the write target with the tabs below, or run with neither flag to inspect the plan without touching any branch. {% tabs %} {% tab title="inspect-only" icon="magnifying-glass" %} Run `fix` without `--apply` or `--open-pr` to get the analysis and a patch reference without touching any branch: ```bash codna fix https://github.com/owner/repo.git --issue "coupon applied before tax" ``` ``` codna: fixing https://github.com/owner/repo.git … ✓ codna analyzed https://github.com/owner/repo.git root cause : coupon discount applied before tax instead of after symbol : checkout.total (blast radius: 3) confidence : 88% context : 6,200,000 → 18,400 tokens (337× smaller) agent : repository.verified_agentic_v1 via codna · cost: $0.021 patch : $PATCH_REF (--apply for a local branch · --open-pr to open a PR) ``` The risk simulation does **not** run in this mode. It runs only when you apply (`--apply` or `--open-pr`), which is why `regression risk` is absent here and present in the write paths. {% endtab %} {% tab title="open a PR" icon="code-pull-request" %} The end-to-end flow. `--open-pr` requires a **git URL** (a local path has no remote to push to) and a **write token**. Provide the token with `--github-token` or, more commonly, `$GITHUB_TOKEN`. ```bash export GITHUB_TOKEN=... # write scope: contents + pull-requests codna fix https://github.com/owner/repo.git --ref "$SHA" \ --issue "tests/test_checkout.py::test_total failed" \ --open-pr ``` What happens, in order: 1. A snapshot is taken at `--ref` (or the default branch). 2. Triage produces a focused evidence bundle. 3. The agent plans a patch. 4. A deterministic risk simulation runs. 5. Codna pushes a branch named `codna/` and opens the pull request. The run returns once the pull request exists. Your CI then runs on the branch as it would on any other. What you will see: ``` codna: fixing https://github.com/owner/repo.git … ✓ codna analyzed https://github.com/owner/repo.git root cause : coupon discount applied before tax instead of after symbol : checkout.total (blast radius: 3) confidence : 88% · regression risk: 4% context : 6,200,000 → 18,400 tokens (337× smaller) agent : repository.verified_agentic_v1 via codna · cost: $0.021 ✓ opened pull request: https://github.com/owner/repo/pull/123 ``` Field by field: | Line | What it means | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `root cause` | The agent's diagnosis of why the issue occurs. | | `symbol` | Impacted symbol(s) and `blast radius`: how many call sites or dependents the change touches. Omitted when there are none. | | `confidence` | Planner confidence in the fix, as a percentage. `regression risk` is appended when the simulation produced one. | | `context` | Raw repo tokens reduced to the evidence-bundle tokens, with the reduction ratio. | | `agent` | The runtime model that produced the patch, plus token counts and the run cost in USD when reported. | | `✓ opened pull request` | The URL of the pull request. If the change was applied but no URL came back, this line reads `applied (no PR url): `. | | {% endtab %} | | {% tab title="apply locally" icon="code-branch" %} Use `--apply` (not `--open-pr`) to apply the patch to a local branch. The risk simulation still runs first; nothing is pushed and no PR is opened: ```bash codna fix . --issue "coupon applied before tax" --apply ``` ``` ... applied : branch codna/9f2c1a7d3e5b4a60 @ /path/to/checkout ``` The branch is named `codna/`. The trailing field is the checkout path, or the commit SHA when no path is returned. Add `--tests` to verify: Codna runs the repository's tests in a sandbox, applies the patch, re-runs the tests, and re-fixes up to `--max-iterations` times until they pass. ```bash codna fix . --tests --apply --max-iterations 3 ``` 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. Set `fix.test_command` in `codna.yaml` when the tests do not run with plain `pytest`. {% hint style="warning" %} `--open-pr` does not work against a local path: Codna exits with `--open-pr needs a git URL (a local path has no remote to push to).` Pass a git URL with a write token, or use `--apply` for a local branch. {% endhint %} {% endtab %} {% endtabs %} **The generated PR description.** When you do not pass `--pr-body`, Codna writes a structured description. The title defaults to `codna: fix `. The body looks like: ```markdown Automated fix by **codna**. **Issue:** tests/test_checkout.py::test_total failed **Root cause:** coupon discount applied before tax instead of after **Symbols:** checkout.total **Confidence:** 88% _Review before merging._ ``` Override either with `--pr-title "..."` and `--pr-body "..."`. Target a non-default branch with `--base-branch release/2.1`. **Deriving failing tests from CI.** In a pipeline, skip `--issue` and let Codna read the failing tests straight from a JUnit/pytest report. Each `` with a `` or `` becomes a failing-test signal, and the issue text is derived from them: ```bash codna fix https://github.com/owner/repo.git --ref "$SHA" \ --from-junit reports/junit.xml \ --open-pr ``` The derived issue reads like `3 failing test(s): tests/test_checkout.py::test_total; ...` (the first eight are listed). If the report contains no failures, Codna falls back to requiring `--issue`. {% endstep %} {% endstepper %} ## Expected result After this flow, Codna is installed, `codna --version` prints the installed CLI version, `codna triage` reports suspect files plus the context-reduction ratio, and `codna fix --open-pr` opens a pull request when the target is a git URL and a write token is available. If you used `--apply` instead, Codna writes a local branch named `codna/` and prints the checkout path or commit. ## Troubleshooting Hit an error? See [Troubleshooting](/reference/troubleshooting.md) for every message and its one-line fix. Codna prints errors as JSON on stderr; the `message` field names the fix. One rule worth knowing up front: a **local path** (`.`, `/abs/path`) works for `triage`, inspect-only `fix`, and `fix --apply`; `fix --open-pr` needs a **git URL** with a write token, since a local checkout has no remote to push to. ## Next steps * Let the [GitHub App](/guides/github-app.md) review every pull request and open fixes on `@codna fix`. * Add Codna to Cursor or Claude Desktop with `pip install "codna[mcp]"` and `codna mcp install` (see [MCP Server](/guides/mcp.md)). * Wire Codna into CI with the [GitHub Action](/guides/github-action.md). * Prove which scanner findings are reachable with `codna secure` (see [Security Autofix](/guides/security-autofix.md)). --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.codna.ai/getting-started/quickstart.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.