Other Commands

This page covers additional coverctl commands for badges, trends, and coverage analysis.

pr-comment

Post coverage reports as comments on GitHub, GitLab, or Bitbucket pull requests/merge requests.

coverctl pr-comment [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`-p, --profile`	Coverage profile path	`.cover/coverage.out`
`--base-profile`	Base coverage profile for comparison
`--provider`	Git provider: `github`, `gitlab`, `bitbucket`, `auto`	`auto`
`--pr`	PR/MR number	auto-detected
`--owner`	Repository owner/namespace	auto-detected
`--repo`	Repository name	auto-detected
`--update`	Update existing comment instead of creating new	`true`
`--dry-run`	Generate comment without posting	`false`

Provider Auto-Detection

The provider is automatically detected from environment variables:

Provider	Environment Variables
GitHub	`GITHUB_TOKEN`, `GITHUB_REPOSITORY`
GitLab	`GITLAB_TOKEN`, `CI_JOB_TOKEN`, `CI_MERGE_REQUEST_IID`
Bitbucket	`BITBUCKET_TOKEN`, `BITBUCKET_WORKSPACE`, `BITBUCKET_REPO_SLUG`

Examples

# GitHub Actions (auto-detects everything)
coverctl pr-comment --pr ${{ github.event.pull_request.number }}

# GitLab CI (MR number auto-detected from CI_MERGE_REQUEST_IID)
coverctl pr-comment

# Bitbucket Pipelines (PR number auto-detected from BITBUCKET_PR_ID)
coverctl pr-comment

# With coverage comparison to base branch
coverctl pr-comment --pr 123 --base-profile main-coverage.out

# Explicit provider
coverctl pr-comment --provider gitlab --pr 42

# Preview comment without posting
coverctl pr-comment --pr 123 --dry-run

Comment Format

The generated comment includes:

Overall coverage percentage and change
Domain-level coverage breakdown with status indicators
List of changed files with coverage deltas (when base profile provided)
Pass/fail status based on configured thresholds

compare

Compare coverage between two profiles to show improvements and regressions.

coverctl compare [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`--base`	Base coverage profile (required)
`--head`	Head coverage profile	`.cover/coverage.out`
`-o, --output`	Output format: `text`, `json`	`text`

Examples

# Compare main branch to current
coverctl compare --base main-coverage.out --head coverage.out

# Compare two saved profiles
coverctl compare --base v1.0.out --head v2.0.out

# JSON output for CI parsing
coverctl compare --base main.out -o json

Output

Coverage Comparison
───────────────────
Base:  78.5%
Head:  82.1%
Delta: +3.6%

Improved Files (5):
  internal/core/validator.go   65.2% → 85.4%  (+20.2%)
  internal/api/handler.go      72.1% → 78.3%  (+6.2%)
  ...

Regressed Files (1):
  internal/cli/format.go       90.0% → 87.5%  (-2.5%)

badge

Generate an SVG coverage badge for your README.

coverctl badge [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`-p, --profile`	Coverage profile path	`.cover/coverage.out`
`-o, --output`	Output file path	`coverage.svg`
`--label`	Badge label text	`coverage`
`--style`	Badge style: `flat`, `flat-square`	`flat`

Examples

# Generate default badge
coverctl badge

# Custom style and label
coverctl badge --style flat-square --label "test coverage"

# Custom output path
coverctl badge -o docs/badge.svg

trend

Show coverage trends over time using recorded history.

coverctl trend [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`-p, --profile`	Coverage profile path	`.cover/coverage.out`
`--history`	History file path	`.cover/history.json`
`-o, --output`	Output format: `text`, `json`	`text`

Example

# Show coverage trend
coverctl trend

# JSON output
coverctl trend -o json

Output

Coverage Trend (last 10 entries)
────────────────────────────────
Date         Commit    Coverage  Change
2024-12-23   abc1234     82.1%   +0.5%
2024-12-22   def5678     81.6%   +1.2%
2024-12-21   ghi9012     80.4%   -0.3%
...

record

Record current coverage to history for trend analysis.

coverctl record [flags]

Note: Prefer profiles produced by coverctl run or coverctl check so the history reflects the same -coverpkg instrumentation that policy checks use. When using --run, pass test selection via --test-run (or --test-arg=-run=...) since --run is reserved to trigger coverage execution.

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`-p, --profile`	Coverage profile path	`.cover/coverage.out`
`--history`	History file path	`.cover/history.json`
`--commit`	Git commit SHA	auto-detected
`--branch`	Git branch name	auto-detected
`--run`	Run coverage before recording history	`false`
`-l, --language`	Override language detection	auto
`-d, --domain`	Filter to specific domain (repeatable)	all domains
`--tags`	Build tags (e.g., `integration,e2e`)
`--race`	Enable race detector	`false`
`--short`	Skip long-running tests	`false`
`-v`	Verbose test output	`false`
`--test-run`	Run only tests matching pattern
`--timeout`	Test timeout (e.g., `10m`, `1h`)
`--test-arg`	Additional go test argument (repeatable)

Examples

# Record with auto-detected git info
coverctl record

# Explicit commit and branch
coverctl record --commit abc1234 --branch main

# Run coverage before recording history
coverctl record --run --tags integration

CI Integration

- name: Record coverage
  run: |
    coverctl check
    coverctl record --commit ${{ github.sha }} --branch ${{ github.ref_name }}

suggest

Suggest optimal coverage thresholds based on current coverage.

coverctl suggest [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`-p, --profile`	Coverage profile path	`.cover/coverage.out`
`--strategy`	Strategy: `current`, `aggressive`, `conservative`	`current`

Strategies

Strategy	Description
`current`	Set thresholds slightly below current coverage
`aggressive`	Push for higher thresholds
`conservative`	Lower thresholds for gradual improvement

Example

# Get suggestions
coverctl suggest

# Aggressive strategy
coverctl suggest --strategy aggressive

Output

Suggested Thresholds
────────────────────
Domain   Current  Suggested  Reason
core       87.3%       85%   Slightly below current (buffer for variance)
api        81.2%       80%   Slightly below current
cli        76.4%       75%   Slightly below current

debt

Show coverage debt report identifying files that need more tests.

coverctl debt [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`-p, --profile`	Coverage profile path	`.cover/coverage.out`
`-o, --output`	Output format: `text`, `json`	`text`

Example

coverctl debt

Output

Coverage Debt Report
────────────────────
File                           Current  Required  Shortfall
internal/core/validator.go       65.2%      85%     -19.8%
internal/api/handler.go          72.1%      80%      -7.9%
────────────────────
Total Debt: 27.7%
Health Score: 73/100

ignore

Show configured exclude patterns and ignored files.

coverctl ignore [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`

Example

coverctl ignore

Output

Configured Excludes
───────────────────
- **/generated/**
- **/mocks/**
- internal/testdata/*

Ignored Files (matching excludes)
─────────────────────────────────
- internal/generated/proto/api.pb.go
- internal/mocks/service_mock.go

detect

Auto-detect domains and write configuration.

coverctl detect [flags]

Flags

Flag	Description	Default
`-c, --config`	Config file path	`.coverctl.yaml`
`--dry-run`	Preview config without writing	`false`
`-f, --force`	Overwrite existing config	`false`

Examples

# Preview detected domains
coverctl detect --dry-run

# Write config
coverctl detect

# Overwrite existing
coverctl detect --force

version

Show version information.

coverctl version

Output

coverctl v1.4.0 (abc1234) built 2024-12-23

help

Show help for any command.

coverctl help [command]

# Examples
coverctl help
coverctl help check
coverctl check --help