> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/c++-agent-for-windows-beta/c++-agent-parameter-reference-windows.md). # C++ Agent Parameter Reference (Windows) Parameter reference for the Windows/MSVC C++ agent, grouped by command. For Linux/GCC parameters, see the [C++ Agent Parameter Reference Table](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/agent-configuration-parameters/go-agent-parameter-reference-table.md). ### `integrateMsBuild` Injects SeaLights MSBuild targets into the solution tree. Alias: `prepareForMsBuild`. | Parameter | Aliases | Description | Required | | -------------------------- | ---------------------------------- | ------------------------------------------------------------------- | -------------------------------- | | `--dir` | `--projectsRoot`, `--solutionRoot` | Root directory for `.sln` and `.vcxproj` discovery | Yes | | `--gtest` | | Enable the GTest event-listener shim | No | | `--gtest-include-projects` | `--gtest-include` | Glob that forces shim injection into projects | No | | `--gtest-exclude-projects` | `--gtest-exclude` | Glob that skips GTest shim injection | No | | `--gtest-header-path` | | Override the GTest include directory | No | | `--gtest-strict` | | Fail when a detected GTest project cannot resolve `` | No | | `--undo` | | Restore `Directory.Build.targets` from backup | No | | `--recursive` | | Integrate every discovered subdirectory root | No | | `--force-static-libs` | | Instrument static libraries consumed from another solution | No | | `--include` | | Instrument only files matching the glob | No | | `--exclude` | | Skip files matching the glob | No | | `--configuration` | | Restrict integration to one configuration, such as `Release` | No | | `--dry-run` | | Preview changes without writing files | No | | `--tokenFile` | `-tf` | Path to a SeaLights token file | One of `--token` / `--tokenFile` | | `--token` | `-t` | SeaLights token inline | One of `--token` / `--tokenFile` | `--gtest` detects projects that resolve `` automatically. ### `config` Creates a build session and writes its ID to a file. Subsequent commands consume this file. | Parameter | Description | Required | | ---------------------- | ----------------------------------------------------------- | -------------------------------- | | `--appName` | Application name registered in SeaLights | Yes | | `--buildName` | Unique build identifier, such as a CI run number or Git SHA | Yes | | `--branchName` | Source branch name | Yes | | `--buildSessionIdFile` | Session ID output path; defaults to `buildSessionId.txt` | No | | `--labId` | Lab ID; you can also provide it at test time | No | | `--tokenFile` / `-tf` | Token file | One of `--token` / `--tokenFile` | | `--token` / `-t` | Token inline | One of `--token` / `--tokenFile` | ### `scan` Reads PDB files, writes `.slmap` sidecar files beside each binary, and uploads the build map. | Parameter | Aliases | Description | Required | | ---------------------- | ------------------------------ | ------------------------------------------------- | -------------------------------- | | `--binDir` | `--scanDir`, `--workspacePath` | Directory containing binaries and PDB files | Yes | | `--buildSessionIdFile` | | Session ID file written by `config` | Yes | | `--srcRootDir` | | Source root for relative build-map paths | No | | `--labId` | | Lab ID | No | | `--include` | `--includeFiles` | Comma-separated PDB-path globs to include | No | | `--exclude` | `--excludeFiles` | Comma-separated file globs to exclude | No | | `--enableBatching` | | Send the build map in batches for large solutions | No | | `--tokenFile` / `-tf` | | Token file | One of `--token` / `--tokenFile` | ### `run` Launches the target application as a child process. It sets `PATH` for the tracer DLL and exits with the child process. | Parameter | Description | Required | | ----------------------- | ---------------------------------------------------------------- | -------------------------------- | | `--target` | Path to the test executable | Yes | | `--testStage` | Test stage name, such as `Unit-Tests` | Yes | | `--labId` | Lab ID | Yes | | `--buildSessionIdFile` | Session ID file | Yes | | `--targetArgs` | Arguments for the target executable | No | | `--agentPort` / `-p` | Tracer IPC TCP port; defaults to `31031` | No | | `--instrumentationMode` | `TestsAndCoverage` (default), `Tests`, `Coverage`, or `Disabled` | No | | `--workingDir` | Target process working directory | No | | `--tokenFile` / `-tf` | Token file | One of `--token` / `--tokenFile` | ### `startBackgroundTestListener` / `stopBackgroundTestListener` Starts or stops the background listener daemon. Instrumented processes on its port stream coverage hits and GTest events automatically. | Parameter | Description | Required on start | Required on stop | | -------------------------- | --------------------------------------------------------------------- | ----------------- | ---------------- | | `--testStage` | Test stage name | Yes | No | | `--labId` | Lab ID | Yes | No | | `--buildSessionIdFile` | Session ID file | Yes | Yes | | `--agentPort` / `-p` | TCP port; defaults to `31031` and must match on start and stop | No | No | | `--testListenerSessionKey` | Unique key for listeners sharing a host; must match on start and stop | No | No | | `--instrumentationMode` | `TestsAndCoverage` (default), `Tests`, or `Coverage` | No | — | | `--tokenFile` / `-tf` | Token file | Yes | Yes | ### `startExecution` / `endExecution` Opens or closes a named test stage in SeaLights. Always run `endExecution` in a `finally` block. Aliases: `openTestStage` and `closeTestStage`. | Parameter | Description | Required | | ---------------------- | ---------------------------------------------------- | -------------------------------- | | `--testStage` | Test stage name; use the same value on start and end | Yes | | `--labId` | Lab ID | Yes | | `--buildSessionIdFile` | Session ID file | Yes | | `--tokenFile` / `-tf` | Token file | One of `--token` / `--tokenFile` | ### `uploadReports` Uploads an XML test report for NUnit, MSTest, XUnit, JUnit, and frameworks with JUnit XML output. Alias: `uploadTestReport`. | Parameter | Aliases | Description | Required | | ------------------------ | ---------- | ----------------------------------------------------------------- | -------------------------------- | | `--file` | `--report` | Report file or folder containing report files | Yes | | `--testStage` | | Test stage name | Yes | | `--labId` | | Lab ID | Yes | | `--buildSessionIdFile` | | Session ID file | Yes | | `--useExistingExecution` | | Skip execution lifecycle events when another command manages them | No | | `--tokenFile` / `-tf` | | Token file | One of `--token` / `--tokenFile` | ### Logging Use console and file logging together or separately. ```powershell --logLevel Debug --logAppendFile true --logDir "C:\SeaLights\Logs\" ``` ```powershell --logLevel Debug --logAppendConsole true ``` | Parameter | Description | | -------------------- | ------------------------------------------------------------------------------------------------- | | `--logLevel` | Log level: `Disabled`, `Critical`, `Error`, `Warn`, `Info`, `Debug`, or `Trace`. Default: `Info`. | | `--logAppendConsole` | Enable or disable console logging. Default: `true`. | | `--logAppendFile` | Enable or disable file logging. Default: `false`. | | `--logFilename` | Log file name. Default: `cli_{command}_{time}_{pid}.log`. | | `--logDir` | Log directory for the agent and tracer. Default: `..\logs`. | ### Runtime files Keep these agent-package files available at test time. | File | Role | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `sltracer_x64.dll` / `sltracer_x86.dll` | Runtime tracer that `/Gh` injects. Put it on `PATH` or beside the test EXE. `run` adds the agent directory to `PATH`. | | `.slmap` | RVA-to-function-name map from `scan`. Keep it beside its `.exe` and regenerate it on every rebuild. | | `msdia140.dll` | DIA SDK for PDB scanning during `scan`. The agent package includes it. | | `sltracer_loader_x64.lib` / `sltracer_loader_x86.lib` | CRT-agnostic loader that `integrateMsBuild` links into EXE projects. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/c++-agent-for-windows-beta/c++-agent-parameter-reference-windows.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.