> 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 Complete reference for every Codna CLI command, its flags, and usage. `codna` is the single command you run to understand, fix, review, 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, review a change, or prove which scanner findings are reachable before anyone spends time on them. Every subcommand runs on your machine. There is no engine server to start. The [GitHub App](/guides/github-app.md) and the [GitHub Action](/guides/github-action.md) run these same commands. ## Global behavior Credentials come from the environment or the OS keychain. ```bash codna key set anthropic # hidden prompt; stored in the OS keychain export OPENAI_API_KEY="your-provider-key" # or any other supported provider key ``` | Variable | Default | Meaning | | ------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / … | (none) | Provider key for model-backed fixes and reviews. Or store one with `codna key set`. | | `CODNA_API_KEY` | (none) | Your Codna key, stored by `codna login`. Needed only when Codna is pointed at a remote engine. | | `GITHUB_TOKEN` / `CODNA_GITHUB_TOKEN` | (none) | Write token for `fix --open-pr` and `review --post`. | 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 reads it directly. If `repo` starts with `http://` or `https://`, or ends in `.git`, it is fetched. 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.** `triage`, `fix`, `review`, `secure`, and `impact` 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 as JSON and exits `1`. See [Exit codes and errors](#exit-codes-and-errors). ```bash codna --version codna # prints help, exits 0 ``` {% hint style="info" %} `codna` needs no engine URL and no Codna key for local CLI runs. If you set a remote engine URL (`CODNA_ENGINE_URL`) without a key, the run fails with `no API key — set CODNA_API_KEY (your codna key).` in the `message` field of the JSON error. The MCP server (`codna mcp`) is different: every tool call requires the one-time free `codna login` device authorization. {% endhint %} ## Commands Pick a tab for the command you want. Each tab carries that command's synopsis, options table, and examples. {% tabs %} {% tab title="triage" icon="magnifying-glass" %} 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. ``` codna triage [repo] [--ref REF] [--issue TEXT] [--json] ``` | 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. | | `--json` | flag | off | Emit the result as JSON. | 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). ```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 will see. The values show the format; Codna prints the measured values for your repository: ``` 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 printed only when a reduction ratio is available. 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, 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. ``` 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 | Run the repository's tests in a sandbox to discover failures, then fix them. | | `--apply` | flag | off | Apply the patch to a new local branch named `codna/`. | | `--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`. Precedence: this flag, then `fix.test_command` in the repository's `codna.yaml`, then a runner the repository declares (`pixi run test`, `uv run pytest`), then `pytest`. Any pytest it reaches 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, e.g. `openai/gpt-5`. | | `--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. Includes a top-level `pull_request_url` with `--open-pr`. |
### 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 `` 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": {} } } ``` ### 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 ```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) Discover the failing tests, fix, and re-run until green codna fix . --tests --apply --max-iterations 3 # 4) 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 # 5) 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). The values show the format: ``` codna: fixing . … ✓ codna analyzed . root cause : total() applies the coupon twice when stacking is enabled symbol : OrderService.total (blast radius: 3) confidence : 86% context : 2,910,442 → 18,000 tokens (162× 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) ``` What you'll see (`--open-pr`): ``` ✓ opened pull request: https://github.com/acme/shop/pull/482 ``` What you'll see (`--apply`): ``` applied : branch codna/9f2c1a7d3e5b4a60 @ /path/to/checkout ``` If the apply step fails, Codna does not abort the run; it prints the error and the patch reference so you can recover: ``` apply failed : (patch ref: $PATCH_REF) ``` {% 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 codna key set openai # or export OPENAI_API_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. Codna never merges. {% endstep %} {% endstepper %} {% endtab %} {% tab title="review" icon="magnifying-glass-plus" %} 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](/guides/review.md) for the verdict, the red-head note, and the registry check. ``` 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] [--triage [--issue TEXT] [--ref REF]] ``` | 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 and costs more. | | `--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). | | `--model` | model | provider default | Review model, e.g. `openai/gpt-5`. | | `--github-token` | token | env | Write token for `--post`. Falls back to `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. | | `--json` | flag | off | Emit the review result as JSON. | | `--triage` | flag | off | Legacy mode: risk triage (suspect files and symbols) instead of findings. Accepts `--issue` and `--ref`. | ```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, 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. ``` 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] [--json] ``` | 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 2.1.0 output (CodeQL/Semgrep/Snyk/Trivy). | | `--engine` | `local` \| `remote` | `local` | Reachability engine. `local` is the bounded in-process classifier and never claims `exploitable`; `remote` sends classification to the Codna engine over HTTP. | | `--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 eligible finding. Requires `--engine remote`, a resolved manifest and a write token. | | `--json` | flag | off | Emit the reachability result as JSON. |
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 → [production-reachable] js/sql-injection (taint) autofix-eligible · [unreachable] py/weak-hash (config) no reachable path from an entry point · [unknown] js/xss (taint) unknown findings are never auto-fixed summary: production-reachable=1, unknown=1, unreachable=5 · autofix-eligible: 1 ``` 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): ```bash codna secure . --from-sarif results.sarif --engine local --fix ``` {% hint style="info" %} The full security workflow (SARIF provenance, the `codna-security.yaml` manifest, the sandboxed worker, attestations, and the privilege-separated PR writer) is on the [Security Autofix](/guides/security-autofix.md) 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. See [GitHub Action § Security-proof flow](/guides/github-action.md#security-proof-flow-two-job-privilege-separation) for the two-job layout. ``` 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 bundle 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. {% 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. Needs the `mcp` extra: `pip install "codna[mcp]"`. ``` 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 (Cursor only). | `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](/guides/mcp.md). {% endtab %} {% tab title="impact" icon="list-check" %} 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. ``` 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 (an empty subset prints 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 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. ``` 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 for very large repositories (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 ``` See [Code Memory](/concepts/memory.md). {% endtab %} {% tab title="ci" icon="server" %} 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](/reference/adaptive-concurrency.md). ``` codna ci admit --job-class CLASS [--meta K=V ...] codna ci release [--lease PATH] codna ci status ``` | Subcommand | Meaning | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `admit` | Wait for fleet capacity before a CI job does real work. `--job-class` is a stable identity for this kind of job (e.g. `ci/unit-tests`). | | `release` | Release a fleet slot and record the job's duration. `--lease` defaults to `$CODNA_CI_LEASE`. | | `status` | Show the fleet's capacity budget and what is running. | | {% endtab %} | | | {% endtabs %} | | ## Operational commands Setup and runtime commands. Each links to its detailed page. | Command | Synopsis | Purpose | | -------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `codna login` | `codna login [--token TOK] [--no-browser]` | Sign this machine into your Codna account with a device code, store the key in the OS keychain, and install the on-device memory runtime (skipped when already installed), then check for a model key. `--token` (or `$CODNA_TOKEN`) skips the browser. | | `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 model provider key in the OS keychain. Values are never shown. See [Models & BYOK](/concepts/models-and-byok.md). | | `codna status` | `codna status` | Concise health: runtime, code memory, keys. See [Local runtime](/reference/operations.md). | | `codna doctor` | `codna doctor [--start-stack \| --stop-stack]` | Inspect the local runtime; start or stop it. See [Local runtime](/reference/operations.md). | | `codna report` | `codna report [--product P] [--body TEXT] [--attach-diagnostics] [--dry-run]` | File a bug, request or question to [thyn-ai/feedback](https://github.com/thyn-ai/feedback). See below. | ### `codna report` Files a report to the public [thyn-ai/feedback](https://github.com/thyn-ai/feedback) repo, the front door for algenta, codna, telys, and sqai. The same submission path the `codna_report_bug` MCP tool uses (see [MCP Server](/guides/mcp.md#codna_report_bug)), so a human and an agent land in the same place with the same fields. ``` codna report "codna fix hangs on a monorepo" --product codna --body "steps to reproduce..." ``` | Flag | Value | Default | Meaning | | ---------------------- | ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--product` | `algenta \| codna \| telys \| sqai \| accounts \| docs` | `codna` | Which product this is about. | | `--body` | text | `""` | The description. Omit it in an interactive terminal and you're prompted for it; a script or an agent piping this command is never blocked waiting for input. | | `--attach-diagnostics` | flag | off | Attach the same redacted output `codna doctor` prints: presence and source of config, never a secret value. | | `--dry-run` | flag | off | Print exactly what would be sent; submits nothing. | Filing needs a GitHub token (`GITHUB_TOKEN`, `GH_TOKEN`, or an already-authenticated `gh` CLI). Without one, or if the network call fails, `codna report` does not error out: it prints a pre-filled `github.com/.../issues/new` link to finish submitting yourself, and saves a local copy of what you typed under `~/.codna/reports/` (or `CODNA_RUNTIME_ROOT`). ## 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` | Sign-in 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 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/reference/cli.md?ask=<question>&goal=<user_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.