# CLI Command Reference

- Section: Documentation > Reference > CLI Command Reference
- Canonical: https://covdbg.com/docs/reference/cli-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

```powershell
# 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, 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 |
|--------|-------|---------------------|-------------|
| `--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` |
| `--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`) |
| `--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 |

### 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:**

| 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) |

#### 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`:

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

With configuration file for filtering:

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

Pass arguments to the target program:

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

Verbose logging for debugging:

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

Silent mode for CI (only target output):

```powershell
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`.

```powershell
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](https://app.covdbg.com), and `covdbg logout` changes none of them.

---

## Subcommand: `convert`

Converts a `.covdb` database to another coverage format.

### Synopsis

```powershell
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`, `GCOV` or `HTML` |
| `--output <path>` | `-o` | Yes | Output path (file for LCOV, 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`) |
| `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:

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

Export to GCOV format:

```powershell
# 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:

```powershell
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](/docs/guides/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

```powershell
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 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:

```powershell
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:

```powershell
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

```powershell
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 |
| `--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:

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

Analyze with filtering:

```powershell
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:

```powershell
# 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`:

```yaml
baseline:
  - "app.exe"
```

```powershell
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

```powershell
covdbg mcp [--workspace <dir>]
```

### 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 |
| `--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](/docs/integrations/mcp/) 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_FOLLOW_CHILDREN` | Also instrument child processes spawned by the target (same as `--follow-children`) |
| `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_TELEMETRY` | `off` sends no telemetry after a run |

Command-line options take precedence over environment variables.

---

## See Also

* [Configuration Reference](/docs/reference/configuration/) - `.covdbg.yaml` file format
* [Quick Start Guide](/docs/getting-started/quick-start/) - Getting started with covdbg
* [Report Formats](/docs/guides/report-formats/) - Output format details
* [Troubleshooting](/docs/reference/troubleshooting/) - Common issues and solutions