CodeDD CLI Guide
Install, authenticate, configure scope, run audits, and understand what runs locally vs on CodeDD
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.8 (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 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
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
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
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
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
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)
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:
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