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

Code Meaning
0 Success
1 General error (process creation failed, invalid arguments, an agent that did not start in a measured process, an agent DLL missing beside covdbg.exe, etc.)
2 Nothing was measured: no function passed the coverage filter, or modules left the program out. From covdbg 1.5.1 the program still ran and an empty database was written; see Nothing Measured

These codes are covdbg's own. A program that fails or crashes is still a run covdbg measured, so covdbg exits 0 once it has written the database, whatever the program's exit code. Below the program's output, covdbg prints how the program exited, for example covdbg: ctest.exe exited with code 8, and when that code is not 0, adds that its own exit code does not carry it. A crash is printed as its status, such as 0xc0000005.

From covdbg 1.5.1, --propagate-exit-code (or COVDBG_PROPAGATE_EXIT_CODE=1) makes covdbg exit with the program's exit code instead, a crash's status included, once the database is written. Use it in a CI step that should fail when the tests fail. covdbg's own errors still exit 1.

Nothing Measured

From covdbg 1.5.1. When no function of the program passes the coverage filter, or modules leaves the program out, and no function of a library selected under modules, nor of a followed child process, passes it either, covdbg still runs the program, unmeasured, as OpenCppCoverage does. Below the program's output it says why nothing was measured:

covdbg: nothing was measured: no function of simd_tests.exe passes the coverage filter of .covdbg.yaml

For a program without debug information covdbg can read, the reason is simd_tests.exe has no debug information covdbg can read or analyse (see the log). For a program that modules does not select (see Shared Library Patterns), it is simd_tests.exe is not selected under modules: in .covdbg.yaml. Where libraries are selected or children followed, the sentence says that none of them had anything to track either, for example simd_tests.exe is not selected under modules: in .covdbg.yaml, and no function of a library selected under modules: passes its coverage filter.

covdbg then writes an empty database to --output, which covdbg convert and covdbg merge take like any other: its reports list no files. It exits 2, or, with --propagate-exit-code, with the program's exit code, so a test binary that holds none of the measured code still runs and still fails the CI step when its tests fail.

Changed in 1.5.1: covdbg did not run the program at all. It stopped with "Failed to initialize coverage tracker - no functions to track", wrote no database, and exited 2, also with --propagate-exit-code. With modules or --follow-children, a run that measured nothing exited 1 with "Nothing was measured" and wrote no database.


Run Mode (Default)

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

Positional Arguments

Argument Description
program The executable to measure: a path, or a name found on PATH; see Finding the Program
args... Arguments to pass to the target program

Finding the Program

From covdbg 1.5.1, covdbg finds program as cmd and CreateProcess find it, so a step such as covdbg --follow-children xmake run UnitTests works as OpenCppCoverage -- xmake run UnitTests does. Before, program had to be an existing file relative to the working directory.

  • A name with a directory or a drive in it (build\tests.exe, .\tests) is a path from the working directory.
  • A bare name (ctest, xmake.exe) is looked for in the working directory first, unless the NoDefaultCurrentDirectoryInExePath environment variable is set, then in each directory on PATH in order. covdbg's own directory is not searched.
  • A name without one of the extensions in PATHEXT is tried with each of them in turn, .exe always among them.
  • Only a file counts, so a folder of the same name in the working directory (the xmake folder of an xmake project) does not hide the program on PATH.
  • covdbg measures executables. A .bat or .cmd found first is passed over for an .exe further on, as CreateProcess does. When there is only a script, covdbg says so and how to measure what it runs: covdbg --follow-children cmd /c build ....
  • When nothing is found, the error names the program, says that PATH was searched, and lists the extensions tried.

The full path found is what covdbg starts and records in the database. The .covdbg.yaml beside the executable and a targets: entry are matched against it too, so covdbg ctest matches target: "ctest.exe". From covdbg 1.5.1, a targets: name is compared with the file name without regard to case, as Windows compares file names (see Target Matching). The program still sees the name you typed as its argv[0].

Options

Option Short Environment Variable Description
--config <path> -c COVDBG_CONFIG Path to .covdbg.yaml settings file
--output <path> -o COVDBG_OUTPUT Output path for the .covdb file (default: .covdbg/coverage.covdb in the working directory)
--mode <mode> COVDBG_MODE Execution mode: ONE_SHOT (default), PERSISTENT
--optimization-mode <mode> COVDBG_OPTIMIZATION_MODE How the agent writes its probes: FAVOR_SPEED (default) or FAVOR_STABILITY; see Optimization Mode. From covdbg 1.5.0
--follow-children COVDBG_FOLLOW_CHILDREN Also instrument child processes spawned by the target and merge their coverage into --output (also settings.follow_children in .covdbg.yaml). A target without symbols, such as ctest.exe, runs unmeasured and only its children are measured. modules in .covdbg.yaml selects the executables of followed processes as it does the program's. A block counts once per process that ran it; in ONE_SHOT mode a line counts 1 however many processes ran it
--propagate-exit-code COVDBG_PROPAGATE_EXIT_CODE Exit with the program's exit code once its coverage is written, instead of 0; see Exit Codes. From covdbg 1.5.1
--stop-on-break COVDBG_STOP_ON_BREAK Let a breakpoint the program does not handle itself (__debugbreak(), DebugBreak()) end it with 0x80000003, as it does without a debugger, instead of continuing past it; see Breakpoints in the program. Like OpenCppCoverage's --stop_on_assert. From covdbg 1.5.1
--crash-dump-dir <dir> COVDBG_CRASH_DUMP_DIR Directory for the dump of each measured process that crashes, created if missing (default: the directory of the --output database); see Crash Dumps. From covdbg 1.5.1
--no-crash-dumps COVDBG_NO_CRASH_DUMPS Write no dump of a measured process that crashes; the crash is still reported. See Crash Dumps. From covdbg 1.5.1
--symbol-engine <engine> Symbol resolver engine: covdbg (default) or native
--log-level <level> COVDBG_LOG_LEVEL Log file level: TRACE, DEBUG, INFO, WARN, ERROR, NONE (default: DEBUG)
--log-file <path> COVDBG_LOG_FILE Custom log file path (default: .covdbg/Logs/covdbg.log)
--http-timeout <seconds> COVDBG_HTTP_TIMEOUT HTTP timeout in seconds for the license service (default: 30)
--help -h Print help message and exit
--version Print version information and exit

Execution Mode

--mode (or COVDBG_MODE) selects what covdbg records for each basic block.

Mode Records Cost
ONE_SHOT (default) Whether each block ran Each probe is taken out at its first hit: the fastest mode. A block that several threads hit before its probe is out is still recorded once
PERSISTENT How many times each block ran Every run of a block is a probe hit

--mode PERSISTENT counts every run of every block. From covdbg 1.5.0, when a block is hit, its probe stays in place: covdbg runs the instruction from a relocated copy and jumps back, so the counts are exact, even when many threads run the same code at once. A few blocks cannot run that way: those that start with an indirect call, a trap such as int3 or ud2, or an ARM64 exclusive load or store. In a process that runs with hardware shadow stacks (CET), no block can. For those, covdbg briefly takes the probe out to run the instruction, so their counts are a lower bound when several threads run them at the same time.

An instruction under a probe that faults, and that the program's exception handler runs again once it has fixed the cause, counts as one run of its block, also when the handler itself (or code it calls) faults under a probe first. covdbg follows up to four such faults nested in one another's handlers on a thread. Past that, the outermost fault's retry counts as another run of its block.

A line's count in every report (Cobertura hits, LCOV DA, GCOV, HTML) comes from the blocks that carry the line, and a function's from its blocks. A line is in more than one block when it is in a template instantiated more than once, in a function inlined in several places, or in code the compiler duplicated. In PERSISTENT mode a line's count is the sum of its blocks' counts: how often the line ran, over all of its copies. In ONE_SHOT mode a line counts 1 when any of its blocks ran and 0 otherwise, and a function counts 1 when it ran. The database records the mode it was written in, as coverage_mode (ONE_SHOT or PERSISTENT) in its metadata table.

Changed in 1.5.1: in ONE_SHOT mode, a line used to count each of its blocks that ran, so a line of a template instantiated for 300 types could be reported with 300 hits. A block that several threads hit at once, before its probe was out, counted each of those threads. covdbg 1.5.1 does not open a database written by covdbg 1.5.0 or earlier: record the coverage again, see Databases from Earlier Versions.

Folded Functions

Functions the linker folds into one (/OPT:ICF, the default of release links, with /Gy) share one copy of their code. Each of them is still a function of its own, by its own name and with the lines of its own source: in the Cobertura <method> elements, LCOV's FN/FNDA/FNF/FNH, the HTML function lists and totals, and the database's function_coverage. Each counts as run when the shared code ran.

Changed in 1.5.1, with the coverage database's schema version 9: the folded functions were one function, named after one of them, which listed the lines of the others' files under its name. covdbg 1.5.1 refuses a database written by covdbg 1.5.0 or earlier, and covdbg 1.5.0 or earlier refuses one written by covdbg 1.5.1: record the coverage again, see Databases from Earlier Versions.

Assembly Outside Procedures

From covdbg 1.5.1. An assembler writes line records for all the code it assembles, but a procedure record only where the source marks a procedure: MASM for PROC ... ENDP, NASM never. covdbg measures the code outside any procedure like the rest, as OpenCppCoverage does: NASM's output, such as the .asm files of OpenSSL when it is linked statically (vcpkg's openssl port), and MASM code after a plain label. Its lines count as covered when they run, and its .asm files are in every report, as far as your files: filters include them.

In the function lists (Cobertura <method> elements, LCOV's FN, the HTML reports), each public label starts a function named after it (global in NASM, PUBLIC in MASM), which runs to the next public label or procedure. A label that is not public, such as NASM's local .loop, starts none: its lines belong to the function of the public label before it. Code before the first public label of its file is a function named after its file and first line, for example aesni-x86_64.asm:21.

Changed in 1.5.1: code outside a procedure was left out, and the .asm files that held only such code were missing from every report, executed or not. Code inside PROC ... ENDP was measured before too.

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 checkout around source_root, see which repository a run is licensed for) 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 sign-in is for one team: a seat in that team covers every repository, and signed in for your personal team, 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.

Changed in 1.5.1: covdbg finds the checkout by walking up from source_root to its root, as git rev-parse --show-toplevel does, so a .covdbg.yaml in a subfolder of a checkout counts for that checkout. It used to read the remote only from the source_root directory itself, and a config in a subfolder named no remote.

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. A credential the service answers and rejects is not an outage: the run is refused, and the console says to run covdbg login.

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. The error names the file and gives the parser's reason, with its line and column, such as a value of the wrong type. From covdbg 1.5.1, an auto-discovered .covdbg.yaml that cannot be loaded stops the run too: covdbg no longer passes over it to the next place, nor ends with "No configuration file found". 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:

Path Description
coverage.covdb The coverage database of a run, unless --output names another path
Logs/covdbg.log Rotating log files (up to 5 files, 15MB each)
crash_<program>_<pid>_<YYYYMMDD>_<HHMMSS>.dmp The dump of a measured process that crashed, when no --output is named; see Crash Dumps

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 and covdbg's own lines beginning covdbg:: the program it starts, how the program exited, where it wrote the database, and a one-line summary (see the Quick Start Guide for an example). Its errors go to stderr. --log-level changes only the log file
  • --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. Each baseline binary is filtered by the targets: entry for its own file name, matched without regard to case from covdbg 1.5.1
  • When two targets: entries differ only in case, or are the same, covdbg uses the first and warns on stderr and in the log (from covdbg 1.5.1), for a run and for analyze; see Entries that differ only in case
  • Shared libraries selected under modules in .covdbg.yaml are measured along with the target and written to the same .covdb as modules of their own; see Shared Library Patterns. From covdbg 1.5.1, modules: include: selects the executable too: the target, and each followed child's executable, is measured only when a pattern selects it, and modules: exclude: leaves it out. An executable left out still runs, its libraries are measured, and its children followed

Breakpoints in the program

From covdbg 1.5.1. A program can break into a debugger itself: __debugbreak(), DebugBreak(), or an assertion helper that does. The program's own handlers (__try/__except, a vectored exception handler) get such a breakpoint first, as they do without covdbg. When none of them takes it, covdbg continues past it, as OpenCppCoverage and Visual Studio's "Continue" do, so the program runs on and the code after the breakpoint is measured. Below the program's output, covdbg says so:

covdbg: continued past 1 breakpoint(s) the program did not handle (__debugbreak, DebugBreak); without a debugger it would have ended at the first

Without a debugger, the program would have ended at that breakpoint with 0x80000003. A test that breaks unconditionally can therefore pass under covdbg and crash on its own. To get the native behaviour, pass --stop-on-break (or set COVDBG_STOP_ON_BREAK=1): covdbg then leaves the breakpoint unhandled, the program ends with 0x80000003, and the coverage up to that point is written. Add --propagate-exit-code to have covdbg exit with that status. The option applies in every followed child covdbg measures.

Crash Dumps

When a measured process crashes (the program, or with --follow-children any process it starts), covdbg writes a full dump of it and says where, below the program's output:

covdbg: 'tests.exe' (4711) crashed with exception 0xc0000005; crash dump written to C:\build\crash_tests_4711_20261025_024316.dmp

A dump is about as large as the process's memory, 10 MB and up.

  • Name: crash_<program>_<pid>_<YYYYMMDD>_<HHMMSS>.dmp, so processes that crash in the same second each keep their own dump. When the name is taken, covdbg adds a counter (_2, _3), and no dump ever replaces another.
  • Location: the directory of the --output database, or .covdbg in the working directory when no output is named. --crash-dump-dir <dir> (or COVDBG_CRASH_DUMP_DIR) puts them in another directory, which covdbg creates if it is missing. When the directory cannot be used, covdbg says so, writes no dump, and the run goes on.
  • Off: --no-crash-dumps (or COVDBG_NO_CRASH_DUMPS=1) writes none; the crash is still reported. A test suite that crashes on purpose, such as death tests or use-after-free checks, can turn them off.
  • MCP: the run tool of covdbg mcp runs covdbg the same way, so its dumps go beside the database it writes.

Changed in 1.5.1: dumps used to be written to the working directory, often the checkout, as crash_dump_<YYYYMMDD>_<HHMMSS>.dmp, and a second crash in the same second replaced the first one's dump. A .gitignore entry for crash_dump_*.dmp no longer matches; use crash_*.dmp, or keep the dumps out of the checkout with --output or --crash-dump-dir.

Optimization Mode

From covdbg 1.5.0. covdbg's agent writes a probe into the target's code at every basic block and takes it out again when the block is hit. --optimization-mode (or COVDBG_OPTIMIZATION_MODE) selects what happens to the protection of those code pages. The value is not case-sensitive; an unknown value is refused and the valid ones are listed.

Mode Probed code pages Use it when
FAVOR_SPEED (default) Stay writable (PAGE_EXECUTE_READWRITE) for the whole run, so a probe is taken out with a plain write You want the fastest run and the target does not mind writable code
FAVOR_STABILITY Get their original protection back once the probes are installed; each probe hit makes the page writable briefly, writes, and restores it The target, or security software on the machine, objects to writable code (W^X), or the target checks its own code pages
  • Cost in ONE_SHOT mode (the default): installing the probes and running a test suite take the same time in both modes
  • Cost in PERSISTENT mode: every probe hit costs more under FAVOR_STABILITY, so prefer FAVOR_SPEED for long persistent runs
  • Scope: the mode applies to the executables the agent instruments. Probes in shared libraries (modules) are written by covdbg from outside the process, and the library's pages keep their protection in either mode
  • The log file records the mode a run used (Optimization mode: ...)

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"

Keep the target's code pages read-only (W^X):

covdbg --optimization-mode FAVOR_STABILITY --output "results.covdb" "tests.exe"

Subcommands: login, logout, whoami

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

covdbg login                    # Prints a page to open and a code to confirm there, then waits until it is confirmed
covdbg login --team <slug>      # The same, for the team with this slug
covdbg login --team personal    # The same, for your personal team
covdbg logout                   # Ends the session on the service and forgets it on this machine
covdbg whoami                   # Says who this machine is signed in as, and for which team
covdbg whoami --json            # The same, as one JSON object

covdbg login signs in with whatever identity provider the service offers (GitHub today), for one team. Without --team, the sign-in page ends with a step where you choose the team. On success it prints:

Signed in as <email> for <team>.
Runs are licensed for <team>. To use another team, run `covdbg login --team <slug>`.
Manage seats and teams at https://app.covdbg.com

The sign-in is kept in the Windows Credential Manager; signing in again replaces it, which is also how you switch teams. Seats, teams and the personal lock are managed at app.covdbg.com, and covdbg logout changes none of them.

covdbg whoami asks the service, with a short timeout, and prints Signed in as <email> for <team>. If the service cannot be reached, it prints the stored sign-in and adds This is the stored sign-in, not confirmed by the service: .... If the service says the session has ended, it prints Not signed in: the session has ended on the service. and asks you to run covdbg login again. When COVDBG_PROJECT_TOKEN is set, it adds that runs use the token instead of the sign-in. It exits with 1 when the machine is not signed in.

covdbg whoami --json prints one object for scripts and tools, with null for anything it does not know:

{"signedIn":true,"email":"you@example.com","accountId":"...","teamName":"Northwind Robotics","teamSlug":"northwind-robotics","teamKind":"...","source":"service","projectToken":false}

source is service when the service has just confirmed the sign-in and local when it is the stored sign-in only. projectToken is true when COVDBG_PROJECT_TOKEN is set.


Databases from Earlier Versions

covdbg 1.5.1 writes version 9 of the coverage database, which gives each folded function a row of its own. There is no migration, in either direction. covdbg 1.5.1 refuses a .covdb written by covdbg 1.5.0 or earlier (schema version 8 or older) when it opens it, before reading anything, and names both versions:

  • covdbg convert exits 1 and writes no report:

    covdbg: Failed to open coverage database: results.covdb - Database schema version 8 is older than this build supports (9), and no migration exists. Regenerate the coverage database with this version of covdbg.
  • covdbg merge exits 1, writes no merged database, and names the input it could not open:

    covdbg: Failed to merge databases: Failed to open input database 'results.covdb': Database schema version 8 is older than this build supports (9), and no migration exists. Regenerate the coverage database with this version of covdbg.
  • The MCP server's open_coverage answers with an error that carries the same text.

Record the coverage again with covdbg 1.5.1: run the tests again, and covdbg analyze again for any database it wrote. covdbg 1.5.0 and earlier refuse a database written by covdbg 1.5.1 the same way, with Database schema version 9 is newer than this build supports (8), so every machine that reads the databases, such as the CI job that merges and converts them, needs covdbg 1.5.1 too.


Subcommand: convert

Converts a .covdb database to another coverage format. A database written by covdbg 1.5.0 or earlier is refused, see Databases from Earlier Versions.

Synopsis

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

Options

Option Short Required Description
--input <path> -i Yes Path to input .covdb file
--format <fmt> -f Yes Output format: LCOV, COBERTURA, GCOV or HTML
--output <path> -o Yes Output path (file for LCOV and COBERTURA, existing directory for GCOV, directory for HTML)
--html-title <text> No Title shown in the HTML report (HTML only)
--html-source-root <dir> No Checkout root used to resolve the recorded relative source paths (HTML only)
--help -h Print help message and exit

Format Requirements

Format Output Path Type Description
LCOV File path Single .lcov file (e.g., coverage.lcov)
COBERTURA File path Single Cobertura XML file (e.g., coverage.xml), from covdbg 1.5.0
GCOV Existing directory Creates *.gcov files inside the directory
HTML Directory Creates index.html, per-file pages and local assets inside the directory, creating it when missing

Examples

Export to LCOV format:

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

Export to Cobertura XML, which Codecov and most CI dashboards read:

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

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

Option Short Required Description
--input <path> -i Yes Input .covdb file(s) to merge (specify multiple times, minimum 2)
--output <path> -o Yes Output merged .covdb file
--help -h Print help message and exit

Merge Behavior

  • Hit counts of the blocks the inputs share add up
  • The merged database is ONE_SHOT when any input was recorded in ONE_SHOT mode, since those counts say only whether a block ran: its lines count 1 at most. It is PERSISTENT when every input was, and its lines count how often they ran. With an input that records no mode (written by covdbg analyze) and none in ONE_SHOT, it records none either, and its lines keep the sum of their blocks' counts
  • Source files are matched by their path relative to each run's source_root, without regard to case, as Windows compares file names (letters outside ASCII too, from covdbg 1.5.1; before, only ASCII letters matched in any case). The lines of one source file then combine, whichever checkout recorded them. A file without a relative path is matched by its absolute path
  • Module, file, function, and basic block information is unified. Functions the linker folded into one (/OPT:ICF) stay a function each, also when only some of the inputs have one of them
  • An input written by covdbg 1.5.0 or earlier is refused by name, and no merged database is written, see Databases from Earlier Versions
  • 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

Option Short Required Description
--input <path> -i Yes Path to input executable (.exe) or DLL
--output <path> -o Yes Output .covdb file
--config <path> -c No Path to .covdbg.yaml for filtering. The targets: entry for the input's file name applies, matched without regard to case (from covdbg 1.5.1), see Target Matching
--source-root <path> No Source root for resolving relative paths
--symbol-engine <engine> No Symbol resolver: covdbg (default) or native
--help -h Print help message and exit

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>] [--query-timeout <ms>]

Options

Option Required Description
--workspace <dir> No Workspace root the client is working in; discover searches it by default. Without it, the server's working directory is searched
--query-timeout <ms> No How long one statement of the query tool may run before it is stopped, in whole milliseconds from 1 to 600000 (default: 5000). Takes precedence over COVDBG_MCP_QUERY_TIMEOUT_MS; see Query limits. From covdbg 1.5.0
--help Print help message and exit

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:

Variable Description
COVDBG_PROJECT_TOKEN The team's project token a CI job runs with, instead of a sign-in
COVDBG_CONFIG Path to .covdbg.yaml settings file
COVDBG_OUTPUT Output path for .covdb file
COVDBG_MODE Execution mode (ONE_SHOT or PERSISTENT)
COVDBG_OPTIMIZATION_MODE How the agent writes its probes (FAVOR_SPEED or FAVOR_STABILITY, same as --optimization-mode)
COVDBG_FOLLOW_CHILDREN Also instrument child processes spawned by the target (same as --follow-children)
COVDBG_PROPAGATE_EXIT_CODE Exit with the program's exit code once its coverage is written (same as --propagate-exit-code)
COVDBG_STOP_ON_BREAK Let a breakpoint the program does not handle end it, as without a debugger (same as --stop-on-break)
COVDBG_CRASH_DUMP_DIR Directory for the dumps of measured processes that crash (same as --crash-dump-dir)
COVDBG_NO_CRASH_DUMPS Write no dumps of measured processes that crash (same as --no-crash-dumps)
COVDBG_LOG_LEVEL Log file level (TRACE, DEBUG, INFO, WARN, ERROR, NONE)
COVDBG_LOG_FILE Custom log file path (default: .covdbg/Logs/covdbg.log)
COVDBG_HTTP_TIMEOUT HTTP timeout in seconds for the license service (default: 30)
COVDBG_MCP_QUERY_TIMEOUT_MS Time limit in milliseconds for one statement of the MCP query tool (1 to 600000, default: 5000; same as covdbg mcp --query-timeout)
COVDBG_TELEMETRY off sends no telemetry after a run

Command-line options take precedence over environment variables.


See Also