CLI Command Reference

covdbg provides a command-line interface for collecting and processing code coverage data from Windows executables.

Overview

covdbg operates in two modes:

• Run mode (default): Execute a program under coverage tracking and produce a .covdb database
• Subcommands: Utility commands for processing coverage data (convert, merge, analyze), the sign-in commands (login, logout, whoami), and mcp, the server for AI coding agents

Synopsis

# Run mode (default)
covdbg [OPTIONS] <program> [args...]

# Subcommands
covdbg <SUBCOMMAND> [OPTIONS]

Exit Codes

---

Run Mode (Default)

Runs <program> under coverage tracking and writes a .covdb database.

Positional Arguments

Options

Resolution Precedence

covdbg uses a clear precedence hierarchy when resolving settings from multiple sources.

Credential Resolution

Licensing takes no options. Every run asks the license service, naming the repository (the git remote of source_root) and the commit author, and the credential it carries is resolved in this order (first match wins):

1. COVDBG_PROJECT_TOKEN environment variable (CI): the team's token, which covers the commit authors who hold a seat in that team
2. The developer's sign-in from covdbg login, kept in the Windows Credential Manager: a seat in any team covers every repository, and without one personal use covers public repositories without limit and one private repository at a time

With neither, the run is refused before the service is asked: there is no anonymous run, and the console names the fix. A public repository is free for whoever asks, so a sign-in is all it costs. covdbg says on the console when reporting is gated (the database then keeps only the ten most-hit files). A repository with no remote is named by its root commit.

The decision the service made is kept in the Windows Credential Manager and reused until it is due for refresh, so a run normally costs no request at all. When the service cannot be reached, the last decision is used until its hard expiry, and a run with nothing cached proceeds on its credential and says so on the console.

Configuration File Resolution

The .covdbg.yaml configuration is resolved in this order:

1. --config CLI option
2. COVDBG_CONFIG environment variable
3. Auto-discovery: .covdbg.yaml in the working directory covdbg is started from
4. Auto-discovery: .covdbg.yaml in the same directory as the target executable

The working directory comes first because that is where the repository is; a build directory is usually somewhere else, and the file belongs to the source tree. When no file is found, the error lists every directory that was searched.

Important: A configuration file is required. If no configuration file is found or cannot be loaded (file not found or invalid YAML), covdbg exits with an error. Every project must provide a .covdbg.yaml file.

The .covdbg Directory

covdbg keeps what a run writes in .covdbg, always in the working directory covdbg is started from, so every project keeps its own next to its .covdbg.yaml. Nothing goes to an application data folder under your profile.

Contents of the directory:

Log Level Resolution

Log level is resolved in this order:

1. --log-level CLI option
2. COVDBG_LOG_LEVEL environment variable
3. settings.log_level in .covdbg.yaml
4. Default: DEBUG

Notes

• The console carries the output of the debugged process; covdbg only adds its errors there, as covdbg: message on stderr
• --log-level NONE disables the log file
• After a run, covdbg reports it to the telemetry service: its version, the Windows version, how long the target ran and its exit code, under the entitlement the run was granted on. No repository, no paths, no coverage. Set COVDBG_TELEMETRY=off in the environment, or telemetry: false under settings in .covdbg.yaml, and nothing is sent; a telemetry service that cannot be reached changes nothing about the run.
• If .covdbg.yaml contains global or target-specific baseline entries, run mode first analyzes those executables, then runs the target and writes a merged .covdb to --output

Examples

Basic usage, signed in once with covdbg login:

covdbg --output "C:\path\to\results.covdb" "C:\path\to\tests.exe"

With configuration file for filtering:

covdbg --config "C:\path\to\.covdbg.yaml" --output "C:\path\to\results.covdb" "C:\path\to\tests.exe"

Pass arguments to the target program:

covdbg --output "results.covdb" "tests.exe" --gtest_filter="MyTest.*" --gtest_repeat=3

Verbose logging for debugging:

covdbg --log-level DEBUG --output "results.covdb" "tests.exe"

Silent mode for CI (only target output):

covdbg --log-level NONE --output "results.covdb" "tests.exe"

---

Subcommands: login, logout, whoami

The sign-in that licenses a developer's runs. None of them takes options or reads .covdbg.yaml.

covdbg login    # Prints a page to open and a code to confirm there, then waits until it is confirmed
covdbg logout   # Ends the session on the service and forgets it on this machine
covdbg whoami   # Prints "Signed in as <email>." or "Not signed in." (exit code 1)

covdbg login signs in with whatever identity provider the service offers (GitHub today). The sign-in is kept in the Windows Credential Manager; signing in again replaces it. Seats, teams and the personal lock are managed at app.covdbg.com, and covdbg logout changes none of them.

---

Subcommand: convert

Converts a .covdb database to another coverage format.

Synopsis

covdbg convert --input <file.covdb> --format <FORMAT> --output <path> [--html-title <text>] [--html-source-root <dir>]

Options

Format Requirements

Examples

Export to LCOV format:

covdbg convert --input "C:\path\to\results.covdb" --format LCOV --output "C:\path\to\coverage.lcov"

Export to GCOV format:

# First create the output directory
New-Item -ItemType Directory -Force -Path "C:\path\to\gcov"
covdbg convert --input "C:\path\to\results.covdb" --format GCOV --output "C:\path\to\gcov\"

Export an HTML report and open it:

covdbg convert --input "C:\path\to\results.covdb" --format HTML --output "C:\path\to\coverage-html" --html-title "My project coverage"
Start-Process "C:\path\to\coverage-html\index.html"

See HTML Reports for what the report contains and how to publish it.

---

Subcommand: merge

Merges multiple .covdb databases into a single combined database. This is useful for aggregating coverage from multiple test runs or test suites.

Synopsis

covdbg merge --input <a.covdb> --input <b.covdb> [--input <c.covdb> ...] --output <merged.covdb>

Options

Merge Behavior

• Hit counts from identical source locations are summed
• Module, file, function, and basic block information is unified
• Metadata from input databases is preserved where possible

Examples

Merge unit tests and integration tests:

covdbg merge --input "C:\path\to\unit.covdb" --input "C:\path\to\integration.covdb" --output "C:\path\to\merged.covdb"

Merge multiple test suite results:

covdbg merge `
  --input "tests-suite1.covdb" `
  --input "tests-suite2.covdb" `
  --input "tests-suite3.covdb" `
  --output "all-tests.covdb"

---

Subcommand: analyze

Analyzes an executable or DLL and produces a .covdb database without executing it. This is useful for:

• Including uncovered code in coverage reports (showing 0% coverage for unexecuted code)
• Pre-generating symbol information for faster runtime coverage collection
• Merging with execution-based coverage to get complete coverage pictures

Synopsis

covdbg analyze --input <binary> --output <out.covdb> [OPTIONS]

Options

Examples

Analyze an executable:

covdbg analyze --input "C:\path\to\app.exe" --output "C:\path\to\app-symbols.covdb"

Analyze with filtering:

covdbg analyze --input "C:\path\to\app.exe" --output "C:\path\to\app-symbols.covdb" --config "C:\path\to\.covdbg.yaml"

Combine analysis with test coverage for complete picture:

# 1. Analyze all code (captures uncovered functions)
covdbg analyze --input "app.exe" --output "all-code.covdb"

# 2. Run tests (captures executed code)
covdbg --output "tests.covdb" "app.exe" --run-tests

# 3. Merge to see covered + uncovered
covdbg merge --input "all-code.covdb" --input "tests.covdb" --output "complete.covdb"

Equivalent single-command flow with .covdbg.yaml:

baseline:
  - "app.exe"

covdbg --config ".covdbg.yaml" --output "complete.covdb" "app.exe" --run-tests

---

Subcommand: mcp

Serves the Model Context Protocol over standard input and output, so an AI coding agent can run coverage and read the results through tools. The server stays running until its input closes.

Synopsis

covdbg mcp [--workspace <dir>]

Options

Runs started through the server take the same environment as run mode, so COVDBG_OUTPUT, COVDBG_PROJECT_TOKEN and the other variables below apply. See MCP Server for client setup and the tool reference.

---

Environment Variables

Most environment variables are alternatives to command-line options; COVDBG_PROJECT_TOKEN and COVDBG_TELEMETRY have no option:

Command-line options take precedence over environment variables.

---

See Also

• Configuration Reference - .covdbg.yaml file format
• Quick Start Guide - Getting started with covdbg
• Report Formats - Output format details
• Troubleshooting - Common issues and solutions