DebtDrone CLI documentation

DebtDrone is an open-source technical-debt scanner with two local interfaces: an interactive terminal UI for investigation and a headless CLI for automation. Both use the same reusable scanner that the DebtDrone SaaS consumes as a versioned Go package. Teams that need hosted repositories, dashboards, organizations, and issue workflows can use the DebtDrone SaaS; this documentation remains focused on the open-source CLI and scanner API.

debtdrone                              # Open the interactive TUI
debtdrone scan . --format=json        # Produce a machine-readable report
debtdrone scan . --fail-on=high       # Enforce a CI quality gate

First time here?

Follow Run your first scan for a predictable installation and scan workflow that does not require Trivy.

Choose your workflow

Explore a repository locally

Launch debtdrone from a repository root, enter /scan, and inspect findings in the master-detail TUI. Settings start from the shared local configuration and remain editable for the session, while completed scan summaries are persisted in the bounded local history store unless persistence is disabled.

Use the interactive TUI →

Automate a scan

Use debtdrone scan to write a text table or JSON array. Add --fail-on when a matching severity should return a non-zero status in CI.

Run scans in CI/CD →

Call DebtDrone from an agent

Connect Codex or Claude Code to the local, repository-scoped MCP server. The scan_repository tool uses the same scanner as the CLI, stays within the root you configure, and does not modify repository contents. MCP is included in v2.2.0 and later.

Connect a coding agent →

Embed the scanner in Go

Go consumers import github.com/endrilickollari/debtdrone-cli/v2/scanner and receive a neutral report without CLI, TUI, or SaaS types.

Understand the scanner architecture →

Documentation by type

Tutorials

Tutorials teach a complete workflow from beginning to end.

• Run your first scan

How-to guides

Use these when you already know the outcome you need.

• Install the CLI
• Explore findings in the TUI
• Run scans in CI/CD
• Configure current scans
• Troubleshoot common failures

Reference

Reference pages describe the exact current interface and reusable APIs.

• Command reference
• Local history storage
• Coverage execution for Go consumers

Concepts

Concept pages explain boundaries and design decisions.

• System architecture
• Scanner ownership and contribution boundary
• MCP and coding agents

Project information

• Contributing
• Documentation deployment
• Versioning and releases

Current capability boundaries

• Headless, MCP, and TUI scans share the versioned local configuration and precedence resolver. Explicit scan flags and MCP inputs remain highest priority.
• .debtdrone.yaml is generated as a preview but is not loaded by scans.
• User-level config commands atomically persist validated settings.
• Headless, MCP, and TUI scans write bounded local history summaries unless history.enabled is false. Headless history commands can inspect and remove them; the TUI browser remains session-only for full finding details.
• Trivy security analysis is optional and can be disabled with --security-scan=false.
• The MCP server is local, stdio-only, restricted to an explicit repository root, and non-destructive to repository contents.

The documentation calls out these limitations explicitly so examples remain safe for scripts, CI systems, and agents.