---
title: CodeDD CLI Guide
description: Install, authenticate, configure scope, run audits, and understand what runs locally vs on CodeDD
category: CodeDD CLI
order: 2
---

# CodeDD CLI Guide

The CodeDD CLI runs audits on your machine while using the CodeDD platform for consolidation, scoring, recommendations, and reporting. Source code never leaves your infrastructure.

Current version: **v0.1.9** (`pip install codedd-cli`).

## What runs where

| Stage | Local (CLI) | CodeDD cloud |
|---|---|---|
| Scope scanning | File discovery, line counting | Scope registration |
| File analysis | LLM review | Result ingestion |
| Complexity | Radon/Lizard metrics | Storage and aggregation |
| Dependencies | Manifest/import scanning | CVE and license enrichment |
| Git statistics | Commit, author, churn data | Storage and analytics |
| Architecture | Component extraction | Persistence and synthesis |
| Scoring & recommendations | — | Consolidation and dashboard |

## Prerequisites

- Python 3.10+ (3.10–3.13)
- CodeDD account with CLI token (Account → CLI Access)
- At least one local Git repository in scope
- At least one LLM API key — Anthropic, OpenAI, Gemini, or Grok

See [CLI Installation](/documentation/cli-installation) for system requirements.

## Quick start

### 1. Generate a CLI token

Account → CLI Access → **Generate Token**. Copy immediately — shown once. Tokens start with `codedd_cli_` and expire after 90 days.

### 2. Install and authenticate

```bash
pip install codedd-cli
codedd auth login --token <your_cli_token>
codedd auth status
```

For CI, set `CODEDD_API_TOKEN` instead of keychain storage.

### 3. Select an audit

```bash
codedd audits list
codedd audits select
```

Choose a single-repo or group audit. This becomes the active context for scope, audit, and fix commands.

### 4. Define scope

```bash
codedd scope add /path/to/repo-a /path/to/repo-b
codedd scope list
codedd scope confirm
```

Group audits allow multiple roots; single audits require exactly one directory.

### 5. Configure LLM keys

```bash
codedd config set-key anthropic   # or openai, gemini, grok
codedd config concurrency 16      # parallel LLM calls (1–75, default 4)
```

Effective concurrency is capped by your server plan (currently 75). Higher values speed up large repos but increase RAM use and may hit provider rate limits.

### 6. Run the audit

```bash
codedd audit start
codedd audit status --watch
```

Options: `--yes` for non-interactive mode; `--show` for a pre-submit summary.

If interrupted, rerun `codedd audit start` — the CLI resumes from its local checkpoint.

After submission, CodeDD runs consolidation on the server. Large repos may take several hours.

### 7. Remediate (optional)

```bash
codedd fix fetch flags
codedd fix flags next --auto
codedd fix fetch vulns
codedd fix vulns next --auto
```

Use Issue Compass selections from the web UI:

```bash
codedd fix selections list
codedd fix selections use 1
```

## Security

- CLI token and LLM keys stored in OS credential manager — not plaintext config
- Config at `~/.codedd/config.toml` (no secrets in this file)
- TLS verification enabled for all API traffic

## Common issues

| Problem | Fix |
|---------|-----|
| No active audit | `codedd audits select` |
| No LLM keys | `codedd config set-key anthropic` (or other provider) |
| Invalid token | Regenerate from Account → CLI Access |
| Scope drift | `codedd scope confirm` then `codedd audit start` |
| Interrupted audit | `codedd audit status` then `codedd audit start` |

## Command reference

**Auth:** `codedd auth login|logout|status`

**Audits:** `codedd audits list|select`

**Scope:** `codedd scope add|list|status|sync|confirm|remove|clear`

**Audit:** `codedd audit start|status [--watch]`

**Config:** `codedd config show|set-key|show-keys|concurrency|provider`

**Fix:** `codedd fix fetch|flags next|vulns next|selections|status|comment|resolve`

**AI agents:** `codedd ai-docs` — structured reference for agent integrations

## Next steps

- [CLI Installation](/documentation/cli-installation)
- [Audit Process Overview](/documentation/audit-process-overview)
- [Data Encryption at Rest](/documentation/data-encryption-at-rest)