> 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 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, authenticate, triage, then fix with `--open-pr`. {% hint style="info" %} Codna is the only thing you install. Repository intelligence runs in-process through the bundled Algenta SDK/core, Telys ships inside the Codna package, and local step artifacts are recorded under the Codna runtime root. There is no engine server to start or configure for the normal product path. {% endhint %} {% stepper %} {% step %} #### Install the CLI {% tabs %} {% tab title="pip" icon="python" %} Install the CLI and MCP server: ```bash pip install codna ``` This installs the `codna` command with the `triage`, `fix`, `review`, `secure`, and `mcp` subcommands, plus `login`, `init`, `doctor`, `status`, and `key`. It needs **no Node, Bun, or separate engine** — the agent runtime is bundled inside the wheel. {% 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 ``` To see every subcommand and the global help: ```bash codna --help ``` ``` usage: codna [-h] [--version] [--config CONFIG] {triage,fix,doctor,secure,secure-open-pr,mcp,review,init,status,login,key} ... Codna — understand, fix & secure your repo. ``` {% endstep %} {% step %} #### Authenticate Installed Codna reads credentials from the process environment or the OS keychain via `codna key set`. The package does not search for `keys.txt`. The simplest setup is one variable: ```bash export CODNA_API_KEY=... # your codna key ``` **The user-facing variables.** The CLI uses the Codna key for licensing/metering, provider keys for model-backed fix planning, and a GitHub token only when you ask it to open a pull request. | Setting | Variables checked, in order | Default if unset | | ------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------ | | API key | `CODNA_API_KEY` | — (required) | | Provider key | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or another supported provider key | — (required only for model-backed fixes without a managed account) | | GitHub write token | `--github-token` flag → `CODNA_GITHUB_TOKEN` → `GITHUB_TOKEN` | — (required for `--open-pr`) | Notes: * The API key is for Codna licensing/metering. Provider keys are used by the local agent-core sidecar when verified planning needs model execution. * The GitHub token is consulted only by `--open-pr`; the CLI flag takes precedence over the environment. * `keys.txt` is a source-checkout convenience only. Packaged users should use environment variables or `codna key set`. For the full provider list and how to pin a model, see [Models & BYOK](/concepts/models-and-byok.md). A complete environment for a local fix plus PR looks like this: ```bash export CODNA_API_KEY="ck_live_..." export OPENAI_API_KEY="sk-..." # or another supported provider key export GITHUB_TOKEN="ghp_..." # only needed for codna fix --open-pr ``` {% 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 LLM tokens. ```bash codna triage [repo] [--ref REF] [--issue TEXT] ``` | 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 | `repo` is resolved the same way for every subcommand: an existing local directory is registered as a `local_repo` connector and read directly by the local SDK/core; a string starting with `http://`/`https://` or ending in `.git` is registered as a `github_repo` connector. Anything else is rejected. **Worked example:** ```bash codna triage . --issue "checkout total is wrong when a coupon is applied" ``` What you will see: ``` 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 wall-clock time for register + snapshot + triage. | | `suspect files` | The files triage ranked as most relevant to `--issue`. Prints `(none)` if the engine returned no candidates. | | `context` | Raw repository token estimate reduced to the focused evidence bundle the agent would consume, with the reduction ratio. | The `context` line appears **only** when the engine returns a reduction ratio. 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` runs the full agent loop: triage, plan a patch with the agent, then — when you ask it to write — run a deterministic risk simulation before applying. With `--open-pr` it pushes a branch and opens a pull request through the engine. ```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 `--from-junit` supplies one. | — | | `--from-junit` | Read failing tests from a JUnit/pytest XML report and derive the issue from them | — | | `--failing-test` | A failing test id; repeatable. Passed to the engine as a signal. | — | | `--tests` | Auto-discover failing tests by running the repo's tests (sandboxed) and 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 + 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 plan 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 fixed https://github.com/owner/repo.git in 38s 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 : verified_agentic_v1 via codna · cost: $0.142 patch : ref://patches/9f3c1a2-checkout-total (--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 actually 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" %} This is the canonical end-to-end flow a reader can follow start to finish. `--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. The git URL is registered as a `github_repo` connector, with the write token attached so the engine can push. 2. A snapshot is taken at `--ref` (or the default branch). 3. Triage produces a focused evidence bundle. 4. The agent plans a patch. 5. A deterministic risk simulation runs and yields a simulation id. 6. The engine pushes a branch and opens the pull request, applying mode `remote_pr`. What you will see: ``` codna: fixing https://github.com/owner/repo.git … ✓ codna fixed https://github.com/owner/repo.git in 41s 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 : verified_agentic_v1 via codna · cost: $0.142 ✓ 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/dependents the change touches. Omitted if the engine returns none. | | `confidence` | Planner confidence in the fix, as a percentage. `regression risk` (probability of loss from the simulation) is appended only when a risk result is present. | | `context` | Raw repo tokens reduced to the evidence-bundle tokens, with the reduction ratio. | | `agent` | The runtime model that produced the patch, plus the run cost in USD when reported. | | `✓ opened pull request` | The URL of the PR the engine opened. If the engine applied the change but returned no URL, this line instead 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/fix-checkout-total @ /path/to/checkout/.codna/worktree ``` The trailing field is the local checkout path, or the commit SHA when no path is returned. {% 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 any context-reduction ratio returned by the engine, 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 and prints the local worktree or commit reference. ## 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 * Add Codna to Cursor or Claude Desktop with `codna mcp` (see the MCP integration page). * Wire Codna into CI so a failed build opens a fix PR automatically (see the GitHub Action page). * Prove which scanner findings are actually reachable with `codna secure` (see the Security page). --- # 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/getting-started/quickstart.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.