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.

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 <gtest/gtest.h>	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 <gtest/gtest.h> 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.

--logLevel Debug --logAppendFile true --logDir "C:\SeaLights\Logs\"

--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.
<binary>.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.