Command Reference

Find .NET agent commands by setup, scan, runtime coverage, test execution, Windows-specific flows, and logging.

Legacy Alias Deprecation Notice

Starting with .NET Agent 3.16.0, SeaLights supports standardised CLI parameter naming across technologies.

Legacy parameter aliases remain supported for backward compatibility, but they are planned for future deprecation. Customers are strongly encouraged to migrate to the standardised CLI parameters as part of their regular maintenance and upgrade process. More information can be found in Configuration Standards.

Use this reference by workflow.

For guided setup, see Scanning the build binaries, Running tests, and Capturing coverage from the application.

Use these sections in order:

1. Common options — reuse authentication, console, and proxy settings.
2. Config and scan — create a session, scan binaries, and finalize multi-module builds.
3. Wrapper command — use run for test frameworks or application processes.
4. Runtime coverage collectors — use the background listener or Windows Collector Service flows.
5. Test execution and results — open a test stage and upload test reports.
6. Logging — collect agent and profiler diagnostics.

Common options

These options repeat across commands.

The command tables below omit them unless a command has unique behavior.

CLI Parameter	Description
--token	SeaLights agent token, used to authenticate to the server.
--tokenFile	Path to a file containing the SeaLights agent token, used to authenticate to the server.
--quiet	Suppresses console feedback messages only. Does not suppress log output when logging is configured to print to the console (Default: false).
--proxy	Address of proxy to run connection through. Use system to use the system proxy.
--proxyUsername	The proxy username if needed.
--proxyPassword	The proxy password if needed.
--tags	One or more tags (comma-separated) to label this instance in the cockpit. Any free text without spaces is allowed, e.g. --tags tag1,tag2.
--settings	Set configuration file for the CLI instance.

Config and scan

Create a build session (config)

This command creates the build session used by later scan and test commands.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--appName	--appname	Required. Name of the application.
--buildName	--buildname	Required. The build label of the current build.
--branchName	--branchname	Required. The source branch of the application.
--buildSessionIdFile	--buildsessionidfile	File where the Build session ID to use can be found.
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards (* = any string, ? = any character). For example: 'com.example.*,io.*.demo,com.?ello.world'
--excludeNamespace	--excludenamespace	Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. For example: 'com.example.*,io.*.demo,com.?ello.world'
--include	--include	Comma-separated list of files or patterns to include (Default: *.exe, *.dll). Supports wildcards. For example: '*-with-dependencies.dll,bad-bad?.exe'
--exclude	--exclude	Comma-separated list of files or patterns to exclude. Supports wildcards. For example: '*-with-dependencies.dll,bad-bad?.exe'
--includeAssemblies	--includeassemblies	Advanced. Comma-separated list of assemblies or patterns to include. By default, all assemblies are included.
--excludeAssemblies	--excludeassemblies	Advanced. Comma-separated list of assemblies or patterns to exclude. Empty by default.
--identifyMethodsBy	--identifymethodsby	Set method identifier type. Possible values: fqn (use method's Fully Qualified Name — produces persistent build scans across multiple builds), mvid (use CLR method token — produces a unique identifier per build).
--identifyMethodsByFqn	--identifymethodsbyfqn	Use Method's Fully Qualified Name as unique method identifier instead of the method's token. Allows producing persistent build scans among multiple builds.
--ignoreGeneratedCode	--ignoregeneratedcode	Ignore scanning methods that are marked with [GeneratedCodeAttribute].
--linesPerHit	--linesperhit	Set how many lines will represent one hit when line level coverage is enabled (Default: 1).
--agentPort	--agentport	Port for IPC communication. SeaLights agent application will listen on this port.

Create a pull request session (prConfig)

Use this command for pull request analysis.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--appName	--appname	Required. Name of the application.
--buildName	--buildname	Required. The build label of the current build.
--branchName	--branchname	Required. The source branch of the application.
--labId	--labid	Required. Sets the lab ID.
--pullRequestNumber	--pullrequestnumber	Required. The number assigned to the Pull Request from the source control.
--pullRequestTitle	--pullrequesttitle	Required. The Pull Request title.
--targetBranch	--targetbranch	Required. The branch to which this PR will be merged into (already reported to SeaLights).
--latestCommit	--latestcommit	Required. The full SHA of the last commit made to the Pull Request.
--repositoryUrl	--repositoryurl	Source control repository URL, from which URLs will be built. May be auto-detected during runtime if available.
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards (* = any string, ? = any character).
--excludeNamespace	--excludenamespace	Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards.
--include	--include	Comma-separated list of files or patterns to include (Default: *.exe, *.dll).
--exclude	--exclude	Comma-separated list of files or patterns to exclude.
--includeAssemblies	--includeassemblies	Advanced. Comma-separated list of assemblies or patterns to include. By default, all assemblies are included.
--excludeAssemblies	--excludeassemblies	Advanced. Comma-separated list of assemblies or patterns to exclude. Empty by default.
--identifyMethodsBy	--identifymethodsby	Set method identifier type. Possible values: fqn (use method's Fully Qualified Name), mvid (use CLR method token).
--identifyMethodsByFqn	--identifymethodsbyfqn	Use Method's Fully Qualified Name as unique method identifier instead of the method's token. Allows producing persistent build scans among multiple builds.
--ignoreGeneratedCode	--ignoregeneratedcode	Ignore scanning methods that are marked with [GeneratedCodeAttribute].
--buildSessionIdFile	--buildsessionidfile	File where the Build session ID to use can be found.
--linesPerHit	--linesperhit	Set how many lines will represent one hit when line level coverage is enabled (Default: 1).
--agentPort	--agentport	Port for IPC communication. SeaLights agent application will listen on this port.

Scan binaries (scan)

The project must contain all the PDB files!

This command uploads the scanned build map for the current session.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--scanDir	--workspacepath	Required. Path to the scanned folder where all binary files are located.
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards.
--excludeNamespace	--excludenamespace	Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards.
--include	--include	Comma-separated list of files or patterns to include (Default: *.exe, *.dll).
--exclude	--exclude	Comma-separated list of files or patterns to exclude.
--includeAssemblies	--includeassemblies	Advanced. Comma-separated list of assemblies or patterns to include. By default, all assemblies are included.
--excludeAssemblies	--excludeassemblies	Advanced. Comma-separated list of assemblies or patterns to exclude. Empty by default.
--uniqueModuleId	--uniquemoduleid	Unique Module ID. Required in the case of a multi-modular build.
--moduleName	--modulename	Sets the module name.
--srcRootDir	--srcrootdir	Source root directory, where all paths will be made relative to.
--scm	--scm	Source control type. Available values: auto, git, tfvc, none (Default: auto).
--scmProvider	--scmprovider	Source control provider (e.g. Github, Bitbucket, Gitlab).
--scmVersion	--scmversion	Source control provider version (e.g. BitBucket version).
--repositoryUrl	--repositoryurl	Source control repository URL. If not provided, the URL of the remote Git origin will be used.
--commitDataFile	--commitdatafile	A path to a file containing commit data. Used from the VSTS extension to report TFVC commits to the server.
--extraScanDirs	--extrascandirs	Adds additional directories to scan. Same filters will be applied.
--extraDbgSearchDirs	--extradbgsearchdirs	Adds additional locations where the agent will search for debug symbols (*.pdb files).
--ignoreGeneratedCode	--ignoregeneratedcode	Ignore scanning methods that are marked with [GeneratedCodeAttribute].
--ignoreDisplayClass	--ignoredisplayclass	Filter out DisplayClass index from method hashing. This can eliminate unexpected modified coverage from added closures.
--enableBatching	--enablebatching	Enables batching of scan results before sending to the server.
--dumpTo	--dumpto	Duplicate buildmap to the specified file.

Finalize a multi-module build (reportBuildStatus)

Use this command after all module scans are complete.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--success	--success	Indicates that the build succeeded (considered failed if not specified).
--message	--message	Additional build status message to report (optional).
--durationMs	--durationms	Build duration in milliseconds (optional).

Wrapper command for tests and application processes

Use run when you can control the process startup command.

Use it in two ways:

• Wrap a supported test framework such as MSTest, NUnit, xUnit, or dotnet test.
• Wrap an application or service process to capture runtime coverage.

See Running tests and Configuring the Profiler-Initiated Collector for end-to-end setup.

Run a process through the agent (run)

A single process can be run with the SeaLights agent as a test listener to capture the test footprints or events from a testing framework (like MSTest, NUnit, and XUnit).

Use the sample that matches your workflow.

Application runtime

In-process tests

Testing framework

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--appName	--appname	Required. Name of the application.
--buildName	--buildname	Required. The build label of the current build.
--branchName	--branchname	Required. The source branch of the application.
--labId	--labid	Required. Sets the lab ID.
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--target	--target	The name (or path) of the target application to run with the test listener.
--targetArgs	--targetargs	Command line arguments to pass to the target application.
--workingDir	--workingdir	Path to the working directory. The current working directory is used if not specified.
--includeProcessFilter	--includeprocessfilter	A list of process names to include for profiling. If empty, all processes are included.
--excludeProcessFilter	--excludeprocessfilter	A list of process names to exclude from profiling. If empty, no processes are excluded.
--includeChildProcesses	--includechildprocesses	Enable instrumentation for child processes (Default: true).
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards.
--excludeNamespace	--excludenamespace	Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards.
--includeAssemblies	--includeassemblies	Advanced. Comma-separated list of assemblies or patterns to include. By default, all assemblies are included.
--excludeAssemblies	--excludeassemblies	Advanced. Comma-separated list of assemblies or patterns to exclude. Empty by default.
--identifyMethodsBy	--identifymethodsby	Set method identifier type. Possible values: fqn (use method's Fully Qualified Name), mvid (use CLR method token).
--identifyMethodsByFqn	--identifymethodsbyfqn	Use Method's Fully Qualified Name as unique method identifier instead of the method's token.
--testStage	--teststage	Sets the test stage (e.g. 'Integration-Test').
--testProjectId	--testprojectid	Set Test Project ID for running tests group.
--prId	--prid	Set Pull Request ID to group tests by PR.
--instrumentationMode	--instrumentationmode	Set instrumentation mode. Possible values: tests, coverage, testsAndCoverage (Default: testsAndCoverage).
--testListenerSessionKey	--testlistenersessionkey	A session key that uniquely identifies the running test listener background instance.
--agentPort	--agentport	Port for IPC communication. SeaLights agent application will listen on this port.
--idleTimeoutSec	--idletimeoutsec	Number of seconds of inactivity after last active profiler disconnected before shutting down. Use -1 to disable.
--startupInactivityTimeoutSec	--startupinactivitytimeoutsec	Number of seconds of inactivity after startup before shutting down. Use -1 to disable.
--footprintsEnableV6	--footprintsenablev6	Use Footprints V6 protocol.
--tiaDisabled	--tiadisabled	Set to true to disable getting TIA Recommendations from the SeaLights backend (Default: false).
--useMsProfiler	--usemsprofiler	Use the MS Instrumentation profiler as uber profiler.
--comRegistration	--comregistration	Register profiler as COM object in the Windows Registry. Required for .NET < 4.0.
--sessionsFile	--sessionsfile	Allow specifying an external file for multiple apps configurations.

Runtime coverage collectors

Use these commands when you need runtime coverage but cannot wrap the target process directly.

Start the background listener (startBackgroundTestListener)

Before using the background test listener, ensure the following environment variables are set on the target process.

Windows

Linux

This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--appName	--appname	Required. Name of the application.
--buildName	--buildname	Required. The build label of the current build.
--branchName	--branchname	Required. The source branch of the application.
--labId	--labid	Required. Sets the lab ID.
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--testListenerSessionKey	--testlistenersessionkey	A random alphanumeric ID (%RANDOM% in command line) that uniquely identifies the running background listener instance. This ID must be passed to any process you want to capture coverage from via SL_CollectorId.
--target	--target	The name (or path) of the target application.
--targetArgs	--targetargs	Arguments to be passed to the target process.
--workingDir	--workingdir	The path to the working directory. If not specified, the current working directory will be used.
--includeProcessFilter	--includeprocessfilter	A list of process names to include for profiling. If empty, all processes are included.
--excludeProcessFilter	--excludeprocessfilter	A list of process names to exclude from profiling. If empty, no processes are excluded.
--includeChildProcesses	--includechildprocesses	Enable instrumentation for child processes (Default: true).
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards.
--excludeNamespace	--excludenamespace	Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards.
--includeAssemblies	--includeassemblies	Advanced. Comma-separated list of assemblies or patterns to include. By default, all assemblies are included.
--excludeAssemblies	--excludeassemblies	Advanced. Comma-separated list of assemblies or patterns to exclude. Empty by default.
--identifyMethodsBy	--identifymethodsby	Set method identifier type. Possible values: fqn (use method's Fully Qualified Name), mvid (use CLR method token).
--identifyMethodsByFqn	--identifymethodsbyfqn	Use Method's Fully Qualified Name as unique method identifier instead of the method's token.
--testStage	--teststage	Sets the test stage (e.g. 'Integration-Test').
--testProjectId	--testprojectid	Set Test Project ID for running tests group.
--prId	--prid	Set Pull Request ID to group tests by PR.
--instrumentationMode	--instrumentationmode	Set instrumentation mode. Possible values: tests, coverage, testsAndCoverage (Default: testsAndCoverage).
--agentPort	--agentport	Port for IPC communication. SeaLights agent application will listen on this port.
--idleTimeoutSec	--idletimeoutsec	Number of seconds of inactivity after last active profiler disconnected before shutting down. Use -1 to disable.
--startupInactivityTimeoutSec	--startupinactivitytimeoutsec	Number of seconds of inactivity after startup before shutting down. Use -1 to disable.
--footprintsEnableV6	--footprintsenablev6	Use Footprints V6 protocol.
--tiaDisabled	--tiadisabled	Set to true to disable getting TIA Recommendations from the SeaLights backend (Default: false).
--useMsProfiler	--usemsprofiler	Use the MS Instrumentation profiler as uber profiler.
--comRegistration	--comregistration	Register profiler as COM object in the Windows Registry. Required for .NET < 4.0.
--sessionsFile	--sessionsfile	Allow specifying an external file for multiple apps configurations.

Stop the background listener (stopBackgroundTestListener)

This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--testListenerSessionKey	--testlistenersessionkey	The session key provided when starting the background test listener.
--agentPort	--agentport	Port for IPC communication (Default: 31031).
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--labId	--labid	Required. Sets the lab ID.

MS Windows-specific commands

Use these commands for IIS, Windows Services, and the Windows Coverage Collector Service.

Install or uninstall the Coverage Collector Service (SL.DotNet.CoverageCollectorService.exe)

This command is commonly used when upgrading your agent version, as it is required to uninstall the Coverage Collector Service from the machine before installing a new version.

All CLI Parameters

CLI Parameter	Description
install	Install the Coverage Collector Service.
start	Start the service. Used together with install.
uninstall	Uninstall the Coverage Collector Service. This command must be executed alone.

Instrument a Windows Service (instrumentService)

This command adds the Environment REG_MULTI_SZ record to the target service in the Windows registry with the environment variables required to start the SeaLights profiler.

Related Windows Registry path: Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<ServiceName>

This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below.

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--serviceName	--servicename	Required. Target service name.
--appName	--appname	Required. Name of the application.
--branchName	--branchname	Required. The source branch of the application.
--buildName	--buildname	Required. The build label of the current build.
--labId	--labid	Required. Sets the lab ID.
--force	--force	Forces overwriting existing registry entries (Default: false).
--scanDir	--scandir	Path to the scanned folder where all binary files are located.
--undo	--undo	Unregisters the SeaLights profiler and removes the Environment Variables from the Registry.
--startCollector	--startcollector	Start the collector as an external process (PIC) alongside the target process. Possible values: run, cdAgent.
--profilerStartup	--profilerstartup	Controls profiler startup blocking behavior. Values: Blocking (default — blocks until collector connects), Async (target app starts during connection).
--targetRuntime	--targetruntime	Specify the target CLR runtime to profile. Possible values: auto, fw (.NET Framework only), core (.NET Core / .NET 5+ only). (Default: auto).
--useMsProfiler	--usemsprofiler	Use the MS Instrumentation profiler as uber profiler.
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards.
--excludeNamespace	--excludenamespace	Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards.
--include	--include	Comma-separated list of files or patterns to include.
--exclude	--exclude	Comma-separated list of files or patterns to exclude.
--includeAssemblies	--includeassemblies	Advanced. Comma-separated list of assemblies or patterns to include.
--excludeAssemblies	--excludeassemblies	Advanced. Comma-separated list of assemblies or patterns to exclude.
--identifyMethodsBy	--identifymethodsby	Set method identifier type. Possible values: fqn, mvid.
--identifyMethodsByFqn	--identifymethodsbyfqn	Use Method's Fully Qualified Name as unique method identifier.
--ignoreGeneratedCode	--ignoregeneratedcode	Ignore scanning methods that are marked with [GeneratedCodeAttribute].
--ignoreDisplayClass	--ignoredisplayclass	Filter out DisplayClass index from method hashing.
--repositoryUrl	--repositoryurl	Source control repository URL.
--includeProcessFilter	--includeprocessfilter	A list of process names to include for profiling.
--excludeProcessFilter	--excludeprocessfilter	A list of process names to exclude from profiling.
--testStage	--teststage	Sets the test stage.
--testProjectId	--testprojectid	Set Test Project ID for running tests group.
--prId	--prid	Set Pull Request ID to group tests by PR.
--instrumentationMode	--instrumentationmode	Set instrumentation mode. Possible values: tests, coverage, testsAndCoverage (Default: testsAndCoverage).
--testListenerSessionKey	--testlistenersessionkey	A session key that uniquely identifies the running test listener background instance.
--agentPort	--agentport	Port for IPC communication.
--idleTimeoutSec	--idletimeoutsec	Seconds of inactivity after last active profiler disconnected before shutting down. Use -1 to disable.
--startupInactivityTimeoutSec	--startupinactivitytimeoutsec	Seconds of inactivity after startup before shutting down. Use -1 to disable.
--footprintsEnableV6	--footprintsenablev6	Use Footprints V6 protocol.
--tiaDisabled	--tiadisabled	Set to true to disable TIA Recommendations (Default: false).
--sessionsFile	--sessionsfile	Allow specifying an external file for multiple apps configurations.

Instrument IIS (instrumentIIS)

This command registers the SeaLights profiler with two specific IIS services: WAS and W3SVC. It is equivalent to running instrumentService twice — once for each of these services.

Related Windows Registry path: Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services

All CLI Parameters

CLI Parameter	Legacy Alias	Description
--appName	--appname	Required. Name of the application.
--branchName	--branchname	Required. The source branch of the application.
--buildName	--buildname	Required. The build label of the current build.
--labId	--labid	Required. Sets the lab ID.
--scanDir	--scandir	Path to the scanned folder where all binary files are located.
--force	--force	Forces overwriting existing registry entries (Default: false).
--undo	--undo	Unregisters the SeaLights profiler and removes the Environment Variables from the Registry.
--startCollector	--startcollector	Start the collector as an external process (PIC) alongside the target process. Possible values: run, cdAgent.
--profilerStartup	--profilerstartup	Controls profiler startup blocking behavior. Values: Blocking, Async (Default: Blocking).
--targetRuntime	--targetruntime	Specify the target CLR runtime to profile. Possible values: auto, fw, core (Default: auto).
--useMsProfiler	--usemsprofiler	Use the MS Instrumentation profiler as uber profiler.
--buildSessionId	--buildsessionid	Session ID of configuration created.
--buildSessionIdFile	--buildsessionidfile	Path to file containing the Session ID of configuration created.
--includeNamespace	--includenamespace	Required. Comma-separated list of namespace or namespace patterns to include. Supports wildcards.
--excludeNamespace	--excludenamespace