CLI overview

The CLI is the substrate behind the MCP coverage server. Every tool the agent calls — check, suggest, debt — is also a CLI command. Humans use the same surface AI agents do; the policy file (.coverctl.yaml) is shared.

The MCP server (coverctl mcp serve) is the canonical way to use coverctl inside an AI coding agent. The CLI is what you use from a terminal — and what powers everything underneath the agent.

Global Flags

These flags work with all commands:

Flag	Description
-q, --quiet	Suppress non-essential output
--no-color	Disable colored output
--ci	CI mode: quiet + no-color + GitHub Actions annotations
-h, --help	Show help for any command

Commands

Core Commands

Command	Description
check	Run coverage and enforce policy
run	Run coverage without policy enforcement
watch	Watch for changes and re-run coverage
report	Analyze an existing coverage profile

Setup Commands

Command	Description
init	Interactive setup wizard
detect	Auto-detect domains and write config

Analysis Commands

Command	Description
badge	Generate SVG coverage badge
trend	Show coverage trends over time
record	Record coverage to history
suggest	Suggest optimal coverage thresholds
debt	Show coverage debt report
ignore	Show configured excludes

See Other Commands for details on analysis commands.

Common Flags

Most commands accept these flags:

Flag	Description
-c, --config	Config file path (default: .coverctl.yaml)
-p, --profile	Coverage profile path
-d, --domain	Filter to specific domain (repeatable)
-o, --output	Output format: text, json, html

Build/Test Flags

The check, run, and watch commands support test flags (Go-specific flags are passed through to go test; other languages use their native test runners):

Flag	Description
--tags	Build tags (e.g., integration,e2e)
--race	Enable race detector
--short	Skip long-running tests
-v	Verbose test output
--run	Run only tests matching pattern
--timeout	Test timeout (e.g., 10m, 1h)
--test-arg	Additional go test argument (repeatable)

See Build Flags Guide for examples.

Exit Codes

Code	Meaning
0	Success
1	Policy violation or coverage below threshold
2	Invalid arguments or configuration error
3	Test or coverage generation failure

Examples

# Basic coverage check
coverctl check

# Check specific domains with JSON output
coverctl check -d core -d api -o json

# Run with integration test tags
coverctl check --tags integration --timeout 30m

# Generate HTML report
coverctl report -o html > coverage.html

# Watch mode during development
coverctl watch -d core