🍪 Your Privacy Matters

We use cookies to enhance your experience. Essential cookies are required for the site to work. You can customize your preferences for analytics and marketing cookies.

CodeDD Logo
Book a demo
DocumentationCodeDD CLICodeDD CLI Guide

CodeDD CLI Guide

Install, authenticate, configure scope, run audits, and understand exactly what the CLI executes locally vs on CodeDD.

CodeDD CLI Guide

What the CLI Is

CodeDD CLI is the terminal interface for running CodeDD audits with local execution. It is designed for teams that want source-code analysis to run on their own machine while still using the CodeDD platform for consolidation, risk scoring, recommendations, and reporting.

What Runs Where

StageRuns Locally (CLI)Runs on CodeDD
Scope scanningDirectory scan, file discovery, line countingScope registration and sync status
File-level auditLLM-based analysis on your machineResult ingestion, audit consolidation
ComplexityRadon/Lizard metric extractionStorage and portfolio aggregation
Dependency analysisManifest/import scanningVulnerability/license enrichment and scoring
Git statisticsCommit, author, merge, branch, release, churn, collaboration extractionStorage and analytics use
ArchitectureLocal component and relationship extractionPersistence and higher-level synthesis
Recommendations-Risk analysis, recommendations, dashboard output

Prerequisites

  • Python 3.11 or higher
  • A CodeDD account
  • At least one local Git repository for the selected audit scope
  • A CLI token generated from your CodeDD account (Account → CLI Access)
  • At least one LLM API key — Anthropic or OpenAI — for local file auditing

1) Generate a CLI Token

From the web app:

  1. Sign in to CodeDD.
  2. Open Account.
  3. Go to CLI Access.
  4. Click Generate Token.
  5. Copy the token and store it securely.

Token status in the UI should show as active when valid.

2) Install the CLI

PyPI install

pip install codedd-cli

Source install (development)

git clone https://gitlab.com/codedd1/codedd-cli
cd codedd-cli
pip install -e .

Verify

codedd --version

3) Authenticate

codedd auth login --token <your_cli_token>

Or run codedd auth login and paste the token when prompted.

Check auth state:

codedd auth status

4) Select the Active Audit

codedd audits list
codedd audits select

The selected audit becomes the active context for scope and audit commands.

5) Define and Confirm Scope

Add one or more local repository roots:

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

Scope confirm performs local scanning and registers scope on CodeDD. If files change later, codedd audit start performs auto-sync and asks for re-confirmation if needed.

6) Configure LLM Provider Key(s)

Set at least one key:

codedd config set-key anthropic
# or
codedd config set-key openai

Optional provider preference:

codedd config provider both

Useful configuration commands:

codedd config show
codedd config show-keys
codedd config concurrency 6

7) Run the Audit

codedd audit start

Frequently used options:

  • --skip-sync skip automatic scope sync check
  • --yes auto-confirm prompts
  • --show print one-shot transparency summary
  • --show-interactive interactive request/payload visibility
  • --show-force-interactive force interactive display on larger audits
  • --debug-llm print LLM debug output

End-to-End Execution Flow

When codedd audit start runs, the CLI executes this sequence:

  1. Validate active audit and local scope
  2. Auto-sync scope vs remote (unless skipped)
  3. Pre-flight on CodeDD (readiness, payment/budget checks)
  4. Register audit start
  5. Execute local analysis:
    • File-level LLM audit
    • Complexity metrics
    • Dependency scanning
    • Git statistics
    • Architecture analysis
  6. Submit structured outputs to CodeDD
  7. Trigger server-side consolidation and recommendations

Git Data Captured by CLI

The CLI submits git statistics aligned with CodeDD storage fields:

  • commit_history
  • author_stats
  • merge_stats
  • branch_stats
  • meta_info
  • time_based_stats
  • release_stats
  • code_churn_stats
  • collaboration_stats

Security and Credential Storage

  • CLI token and LLM API keys are stored in the OS credential manager (not plaintext config).
  • CLI configuration is stored in ~/.codedd/config.toml.
  • TLS verification is enabled for API traffic.

Core Command Reference

Authentication

  • codedd auth login
  • codedd auth logout
  • codedd auth status

Audits

  • codedd audits list
  • codedd audits select [audit_uuid]

Scope

  • codedd scope add <path> [path ...]
  • codedd scope list
  • codedd scope status
  • codedd scope sync
  • codedd scope confirm
  • codedd scope remove <index>
  • codedd scope clear

Audit execution

  • codedd audit start

Configuration

  • codedd config show
  • codedd config set <key> <value>
  • codedd config provider [anthropic|openai|both]
  • codedd config set-key [anthropic|openai]
  • codedd config remove-key <anthropic|openai>
  • codedd config show-keys
  • codedd config concurrency <n>

Common Issues

"No active audit"

Run:

codedd audits select

"No LLM API keys configured"

Run:

codedd config set-key anthropic

or

codedd config set-key openai

Scope drift detected

If local files changed after scope confirm, rerun:

codedd scope confirm
codedd audit start

Recommended Daily Workflow

codedd auth status
codedd audits select
codedd scope status
codedd audit start

Next Reading

Was this page helpful?

Still need help? Contact support