> 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/installation.md).

# Installation

Install the codna CLI from PyPI with one pip command. No Node, Bun, Docker, or separate engine.

Codna installs as a single Python package. `pip install codna` gives you the whole product. The runtime ships inside the wheel.

{% hint style="success" %}
No Node, Bun, Docker, or engine to install or start. After `pip install codna`, `codna fix` works with nothing else on the machine.
{% endhint %}

## Requirements

* Python 3.12 to 3.13.
* macOS or Linux. Codna ships platform-specific wheels; `pip` selects the right one.
* `git` on your `PATH`.

## Install

{% tabs %}
{% tab title="pip" %}

```bash
pip install codna
```

{% endtab %}

{% tab title="pipx" %}

```bash
pipx install codna
```

{% endtab %}

{% tab title="uv" %}

```bash
uv tool install codna
```

{% endtab %}
{% endtabs %}

This installs the `codna` command.

### Optional extras

Base `codna` already includes code memory and the tree-sitter extractors. The extras add optional packages:

| Extra              | Command                                 | Adds                                                                                                                     |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `mcp`              | `pip install "codna[mcp]"`              | The `mcp` package for the `codna mcp` server (Cursor, Claude Desktop). Kept out of base so a plain install stays lean.   |
| `memory`           | `pip install "codna[memory]"`           | `faiss-cpu` and `wordllama`, the on-device semantic reranker recall uses by default. Without it, recall ranks lexically. |
| `memory-rerank`    | `pip install "codna[memory-rerank]"`    | `wordllama` only.                                                                                                        |
| `memory-languages` | `pip install "codna[memory-languages]"` | An alias for the tree-sitter grammars already in base.                                                                   |

See [Code Memory](/concepts/memory.md) and [Language support](/concepts/languages.md).

## Verify

```bash
codna --version
codna status
```

`codna status` reports the runtime, code memory, and configured keys without starting anything. For the full diagnostic, see [Local runtime](/reference/operations.md).

## Keys

Two credentials, two jobs. See [Models & BYOK](/concepts/models-and-byok.md).

1. **A model key.** The provider key the agent uses for `codna fix` and `codna review`. Store it in the OS keychain with `codna key set anthropic` (or `openai`, `gemini`, `google`, `groq`, `mistral`, `openrouter`, `xai`). It is never shown and never passed on the command line.
2. **Your Codna key.** `codna login` signs this machine into your Codna account with a device code and stores the key in the OS keychain. Local CLI runs do not need it; it is used when Codna is pointed at a remote engine, and every MCP tool call (`codna mcp`) checks it — the one-time free device authorization. The GitHub App meters against your linked account instead.

Code memory needs no key. The Telys license ships inside the wheel; the same one-time free `codna login` (device authorization) also installs the on-device memory runtime on a fresh machine, and memory runs fully offline thereafter.

## Upgrade and uninstall

```bash
pip install --upgrade codna
pip uninstall codna
```

Per-repository memory lives in each repo's `.codna-memory/`; device state lives under `~/.codna/` and `~/.telys/`. Delete these independently.

## Offline use

Repository understanding, `codna triage`, `codna impact`, and code memory run fully offline. `codna fix` and `codna review` call your model provider with the evidence bundle or the diff. `codna review` also checks dependency findings against the npm and PyPI registries, unless `privacy.egress: fail-closed` is set. See [Privacy and data](/concepts/privacy.md).

## Next steps

* [Quickstart](/getting-started/quickstart.md) — open your first fix PR.
* [Models & BYOK](/concepts/models-and-byok.md) — set up a model key.
* [Local runtime](/reference/operations.md) — verify and manage the local runtime.


---

# 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/installation.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.