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)

Synopsis

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

# Subcommands
covdbg <SUBCOMMAND> [OPTIONS]Code language: PowerShell (powershell)

Exit Codes

Code	Meaning
0	Success
1	General error (process creation failed, invalid arguments, etc.)
2	No functions passed the coverage filter (nothing to track)

---

Run Mode (Default)

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

Positional Arguments

Argument	Description
program	Path to the executable to debug (must exist)
args...	Arguments to pass to the target program

Options

Option	Short	Environment Variable	Description
--license <JWT>		COVDBG_LICENSE	License token (JWT) for activation
--license-file <path>		COVDBG_LICENSE_FILE	Path to license file
--fetch-license		COVDBG_FETCH_LICENSE	Auto-fetch OSS license using git remote from source_root
--config <path>	-c	COVDBG_CONFIG	Path to .covdbg.yaml settings file
--output <path>	-o	COVDBG_OUTPUT	Output path for .covdb file
--appdata <path>		COVDBG_APPDATA	Custom application data directory path
--mode <mode>		COVDBG_MODE	Execution mode: ONE_SHOT (default), PERSISTENT
--symbol-engine <engine>			Symbol resolver engine: covdbg (default) or native
--log-level <level>		COVDBG_LOG_LEVEL	Console log level: TRACE, DEBUG, INFO, WARN, ERROR, NONE
--log-file <path>		COVDBG_LOG_FILE	Custom log file path (default: <appdata>/Logs/covdbg.log)
--http-timeout <seconds>		COVDBG_HTTP_TIMEOUT	HTTP timeout in seconds for license server (default: 30)
--help	-h		Print help message and exit
--version	-v		Print version information and exit

Resolution Precedence

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

License Resolution

The license is resolved in this order (first match wins):

1. --fetch-license CLI option (auto-provisions OSS license from server)
2. COVDBG_FETCH_LICENSE environment variable
3. --license CLI option
4. COVDBG_LICENSE environment variable
5. --license-file CLI option
6. COVDBG_LICENSE_FILE environment variable

Note: --fetch-license / COVDBG_FETCH_LICENSE is mutually exclusive with --license and --license-file.

Example: If both COVDBG_LICENSE and COVDBG_LICENSE_FILE are set, the direct token (COVDBG_LICENSE) is used.

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 same directory as the target executable

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.

Application Data Directory Resolution

The application data directory stores logs, license cache, and UI settings. It is resolved in this order:

1. --appdata CLI option
2. COVDBG_APPDATA environment variable
3. Default: %APPDATA%\Liasoft\covdbg

Contents of the application data directory:

Path	Description
Logs/covdbg.log	Rotating log files (up to 5 files, 15MB each)
license_cache.json	Cached license validation (reduces server calls)

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: WARN (console), DEBUG (file)

Notes

• --log-level NONE disables all logging output (useful for CI when only test output should be visible)
• File logging always captures DEBUG level and above, regardless of console log level

Examples

Basic usage with license from environment:

$env:COVDBG_LICENSE = "<your-jwt>"
covdbg --output "C:\path\to\results.covdb" "C:\path\to\tests.exe"Code language: PowerShell (powershell)

With configuration file for filtering:

covdbg --config "C:\path\to\.covdbg.yaml" --output "C:\path\to\results.covdb" "C:\path\to\tests.exe"Code language: PowerShell (powershell)

Pass arguments to the target program:

covdbg --output "results.covdb" "tests.exe" --gtest_filter="MyTest.*" --gtest_repeat=3Code language: PowerShell (powershell)

Verbose logging for debugging:

covdbg --log-level DEBUG --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

Silent mode for CI (only target output):

covdbg --log-level NONE --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

---

Subcommand: convert

Converts a .covdb database to another coverage format.

Synopsis

covdbg convert --input <file.covdb> --format <FORMAT> --output <path>Code language: PowerShell (powershell)

Options

Option	Short	Required	Description
--input <path>	-i	Yes	Path to input .covdb file
--format <fmt>	-f	Yes	Output format: LCOV or GCOV
--output <path>	-o	Yes	Output path (file for LCOV, directory for GCOV)
--help	-h		Print help message and exit

Format Requirements

Format	Output Path Type	Description
LCOV	File path	Single .lcov file (e.g., coverage.lcov)
GCOV	Existing directory	Creates *.gcov files inside the directory

Examples

Export to LCOV format:

covdbg convert --input "C:\path\to\results.covdb" --format LCOV --output "C:\path\to\coverage.lcov"Code language: PowerShell (powershell)

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\"Code language: PowerShell (powershell)

---

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>Code language: PowerShell (powershell)

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 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"Code language: PowerShell (powershell)

Merge multiple test suite results:

covdbg merge `
  --input "tests-suite1.covdb" `
  --input "tests-suite2.covdb" `
  --input "tests-suite3.covdb" `
  --output "all-tests.covdb"Code language: PowerShell (powershell)

---

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]Code language: PowerShell (powershell)

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
--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"Code language: PowerShell (powershell)

Analyze with filtering:

covdbg analyze --input "C:\path\to\app.exe" --output "C:\path\to\app-symbols.covdb" --config "C:\path\to\.covdbg.yaml"Code language: PowerShell (powershell)

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"Code language: PowerShell (powershell)

---

Environment Variables

All environment variables can be used as alternatives to command-line options:

Variable	Description
COVDBG_LICENSE	License token (JWT) for activation
COVDBG_LICENSE_FILE	Path to license file
COVDBG_FETCH_LICENSE	Auto-fetch OSS license using git remote from source_root
COVDBG_CONFIG	Path to .covdbg.yaml settings file
COVDBG_OUTPUT	Output path for .covdb file
COVDBG_APPDATA	Application data directory (default: %APPDATA%\Liasoft\covdbg)
COVDBG_MODE	Execution mode (ONE_SHOT or PERSISTENT)
COVDBG_LOG_LEVEL	Console log level (TRACE, DEBUG, INFO, WARN, ERROR, NONE)
COVDBG_LOG_FILE	Custom log file path (default: <appdata>/Logs/covdbg.log)

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