Command Reference
Every slnodejs command and flag, with aliases, defaults, and when to use each flag.
This page lists every slnodejs command and every flag that the command accepts, as printed by npx slnodejs <command> --help in slnodejs 6.2.101. Each flag says when to use it.
For why a flag exists, what it solves, and how to tell whether you need it, see the Flags Guide and, for browser instrumentation, the Browser Agent Flags and Settings Guide.
Settings that have no flag (environment variables only, for example SL_TLS_VERIFY or SL_useLeanCoverageListener) are listed in Configuration → Environment Variables.
Conventions
Flag names are case-insensitive.
--tokenfileand--tokenFileare the same flag. The examples use the recommended name, which--helplists first. Legacy names (for example--workspacePath,--branch,--build) are listed as aliases and still work.Flags that take a value need the value.
--failOnError true, not--failOnError.--useinitialcolor true, not--useinitialcolor. A flag shown as--flag [value]accepts the value or no value.runandmochatake the program or test arguments after--. Everything after--goes to your program or to Mocha. See Understanding the--separator.A failing command exits with status code 0 by default, so SeaLights never breaks your pipeline. Add
--failOnError trueto the commands that must fail the pipeline.Token and build session flags are on every command. They are described once, in Common flags.
dryRunaccepts them but needs them only with--instrumentForBrowsers.
Commands overview
Common flags
These flags are accepted by every command.
--tokenFile <path>
sltoken.txt
File that contains the agent token. Recommended: the token stays out of the process list and CI logs.
--token <token>
The agent token itself. Use only when you cannot write a file; the token is then visible in the process list.
--buildSessionIdFile <path>
buildSessionId for scan, instrument, mocha, run, uploadReports, nycReport; none for the others
File that contains the build session ID written by config or prConfig. Recommended in pipelines: keep the file as a CI artifact between jobs.
--buildSessionId <id>
The build session ID itself. Use when you pass the ID between jobs as a variable. On config and prConfig, it sets your own build session ID instead of a generated one.
--failOnError <true|false>
--failBuild
false
true exits with status code 1 when the command fails. Use it on scan and config when a missing scan must fail the build.
--proxy <url>
HTTP proxy for connections to SeaLights, for example http://127.0.0.1:3333. Use behind a corporate proxy. TLS behavior behind a proxy is described in Troubleshooting → TLS and proxy.
--overrideServer <url>
Connect to this server instead of the one in the token, for example a SeaLights Collector used as a proxy. SeaLights remote configuration takes precedence over this flag.
--skipUpgrade
false
Do not try to upgrade the agent.
Commands that report test data (mocha, run, openTestStage, closeTestStage, uploadReports, nycReport, componentUpdate, componentDelete) and the build commands (config, prConfig, scan) also accept --appName, --branchName (alias --branch) and --buildName (alias --build). They are required only on config. On the other commands, use the build session ID instead.
config
Creates a build session ID for an application, branch and build, and writes it to a file (buildSessionId in the working directory, or --buildSessionIdFile). Every later command of the same build reads that file.
When to use: once per build, before scan. See Generating a Session ID.
--appName <name>
Required. Application name, case-sensitive. Keep it stable between builds.
--branchName <name>
--branch
Required. Branch name, case-sensitive.
--buildName <name>
--build
Required. Build name. Must be unique for each build of the application and branch; reusing it is the most common cause of Module already exists errors. Use the CI build number or commit SHA.
--beControlledVersions
false
First installs the slnodejs version that SeaLights recommends for your account. Use it when you want the dashboard to control the agent version.
prConfig
Creates a build session ID for a pull request build and writes it to a file, like config. SeaLights compares the pull request with its target branch.
When to use: in pull request pipelines, instead of config. See Generating a Session ID → Pull request builds.
--targetBranch <name>
Required. The branch the pull request merges into.
--latestCommit <sha>
Required. Head commit SHA of the pull request source branch.
--pullRequestNumber <n>
Required. Pull request number.
--repositoryUrl <url>
Required. URL of the repository of the target branch.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
scan
Scans the application code of a build and reports its structure (files, methods and branches) to SeaLights. With --instrumentForBrowsers, also writes an instrumented copy of the code for browser coverage. build is an alias.
When to use: once per build (or once per module), after your build produces its output. See Scanning Your Application.
Rules:
A build session can be scanned once. A second scan of the same build session fails, unless each scan has its own
--moduleName.--outputPathand--scanDirmust be different directories.With
--dependencyor--dependenciesFile(integration build),--scanDirand--scmTypeare ignored.--allowCORSrequires--enableOpenTelemetry.
Input and scope
--scanDir <path>
-w, --workspacePath, --distFolderPath, --distPath, --distributablePath
Required (except for integration builds). Directory that contains the code to scan. Scan the files that actually run: the build output for bundled or transpiled code, the source folder for plain Node.js code.
--projectRoot <path>
-p
working directory
Root that file paths are reported relative to. Set it when you run scan from another directory than the project root. Use the same project root for scan and for the test listener.
--excludeFiles <globs>
--excludedPaths
Comma-separated glob patterns to exclude, for example public/**/*.js,test/**/*.js. Prefer a .slignore file; see Configuration → Ignore files for a known issue with this flag.
--recursive
true
Scan subdirectories.
--scanDotFolders
false
Also scan directories whose names start with a dot.
--es6Modules
false
Parse the code as ES modules (import/export). Use for ES module code and for most bundled front-end code.
--babylonPlugins <list>
Comma-separated extra parser plugins. Use jsx for React source with JSX, and decorators-legacy for code with decorators.
--useBabylon [true|false]
true
Use the Babylon parser. Leave the default.
--moduleName <name>
--uniqueModuleId
Module name, case-sensitive and stable between builds. Use it to scan several directories (for example client and server, or packages of a monorepo) into the same build session, one scan per module.
--useModulePrefix
false
Prefix file paths and method IDs with the module name. Use when two modules contain files with the same relative paths.
--partialBuildMapping <n>
Upload the build map in chunks of n files. Use for very large builds that fail or time out during upload.
--compressSlMapping
false
Compress the sl-mapping before upload. SeaLights can set it remotely for your account.
Source control
--scmType <type>
--scm
git reports commits and contributors from the local Git repository. Without it, no source control data is sent. Use git whenever the scan runs inside a Git checkout.
--scmProvider <name>
Github
Github, Bitbucket or Gitlab. Used to build links to your source code.
--repositoryUrl <url>
--scmBaseUrl
URL of the Git remote origin
Repository URL. Set it when the checkout has no origin remote or when the remote URL is not the browsable URL.
--scmVersion <version>
cloud version
Version of an on-premises SCM server. Leave empty for cloud-hosted SCM.
--commit <sha>
Commit ID of the build. Set it when the scan does not run in a Git checkout.
--sendContributors [true|false]
true
Send contributor details for committer reports.
--jobName <name>
CI job name that triggered the build, shown with the build.
--logsUrl <url>
URL of the CI build logs, shown with the build.
Browser instrumentation
These flags take effect only with --instrumentForBrowsers. They are described in Frontend Instrumentation (static) and in the Browser Agent section.
--instrumentForBrowsers
false
Also write an instrumented copy of the code that reports browser coverage. Requires --outputPath. Use for web applications.
--outputPath <path>
-o
Directory for the instrumented copy. Deploy it to the test environment instead of the original.
--instrumentationOnly
false
With --instrumentForBrowsers, instrument without reporting a new build. Use to re-instrument an already scanned build, for example per environment.
--useRelativeSlMapping
false
Key the sl-mapping by paths relative to --scanDir. Required when you instrument later with the instrument command.
--labId <id>
build session ID
Lab ID written into the browser agent configuration. Coverage is attributed to the test stage open on that lab. Use one lab ID per test environment.
--collectorUrl <url>
Load the browser agent from, and send browser coverage to, a SeaLights Collector.
--excludeTokenFromBrowserConfig
false
Leave the agent token out of the browser configuration. Use together with --collectorUrl; without a Collector the agent has no token to authenticate with.
--allowedDomains <list>
Load the browser agent only on these host names. Use when the same instrumented files are served on several domains. An empty string turns the restriction off.
--footprintsMapping <agent|server>
agent
server: SeaLights resolves browser coverage, and the browser does not download the sl-mapping. Use for very large applications where the sl-mapping download slows the page.
--embedCorrectUniqueId
false
Embed the mapping in the instrumented files, so the browser does not download the sl-mapping.
--enableLineCoverage
false
Report line-level coverage in addition to methods.
--splitPreambleIntoFile
false
Write the browser agent configuration to a separate file instead of into every instrumented file. Serve that file with the application and make it non-cacheable.
--preambleFileName <name>
sl-preamble-config.js
Name of the configuration file written with --splitPreambleIntoFile.
--preambleFileUrl <url>
Where the browser loads the configuration file from: {preambleFileUrl}/{preambleFileName}. Pass a full URL, or a relative path without a leading or trailing /. For single-page applications with deep routes, use a full URL.
--toggleBasedBrowserInstrumentation
false
Write instrumented files next to the original files. When /sl-preamble-config.js is not found at the web server root, the browser loads the original files. Requires --splitPreambleIntoFile; classic-script bundles only. See limits.
--skipEsiScripts
false
Do not instrument <script> tags inside ESI comment blocks (<!--esi ... -->).
--enableOpenTelemetry
false
Add the current test context to outgoing Fetch and XHR requests, so back-end agents attribute their coverage to the same test. See Context Propagation.
--allowCORS <origins>
page origin only
Comma-separated origins (or *) that receive the context propagation headers. The list replaces the page's own origin, so include it. Requires --enableOpenTelemetry.
--ctxPropagationOnly
false
Propagate test context without collecting browser coverage.
--delayShutdownInSeconds <n>
30
Written into the browser configuration; the current browser agent does not use it.
--excludeSourceMapFiles <mode>
none
What to do with source map files: none copies them to --outputPath, skipCopy does not copy them, skipAndDelete does not copy them and deletes them from --scanDir. Use skipCopy to keep source maps out of the deployed output.
--preferSourceMapFromFile
false
Use source map files before inline source maps.
--skipInstrumentingFilesWithoutSourceMap
false
Do not instrument files that have no source map. Use to skip vendor bundles that ship without source maps.
Method mapping (advanced)
These flags change how methods are identified. Several of them change method IDs, so turning one on or off makes SeaLights report methods as modified once. Change them only when SeaLights support asks you to, and keep them the same for every build of the application.
--es6Classes [true|false]
Adjust method IDs for TypeScript classes transpiled to ES6 classes.
--enrichPrivateMethods [true|false]
Add accessibility modifiers (for example private) to method details.
--hashIncludeNestedMethods [true|false]
Include nested anonymous functions in the method hash.
--excludeNestedMethods [true|false]
Do not report nested methods.
--sourceHash
Compute method hashes from the source files instead of the generated code.
--enrichByLinesMatch
-l
Experimental method matching algorithm.
--enrichByMethodRange
false
Match methods by their range in the original source. Turns on --recognizeBabelCreateClass.
--recognizeBabelCreateClass
false
Recognize Babel _createClass calls, also in minified code.
--experimentalDeduplicateEnrichedMethodsWithOriginals
false
Remove duplicated methods from the build map.
--newInstrumenter
true
Use the SeaLights instrumenter. Leave the default.
--resolveWithoutHash [true|false]
true
Resolve methods without the hash. Leave the default.
--useBranchCoverage [true|false]
false
Collect branch coverage. SeaLights remote configuration takes precedence.
--autoResolveProjectRoot
false
Append data to the scanned code that lets the test listener find the project root at runtime. Use when the runtime directory layout differs from the build and you cannot set --projectRoot.
Integration builds
--dependency <list>
Components of an integration build, separated by , or ;. Each is a build session ID or appName@branch@build.
--dependenciesFile <path>
-d
JSON array of components, for example [{"appName":"billing","branch":"main","build":"2.3.1"},{"buildSessionId":"<id>"}]. appName is case-sensitive; branchName and buildName are also accepted.
AWS Lambda and V8 coverage
--awsConfigure
false
Write an sl-config.json file into each subdirectory of --scanDir for the SeaLights Lambda layer. The file contains the agent token in plain text; see AWS Lambda.
--awsConfigKeysToIgnore <list>
Comma-separated keys to leave out of sl-config.json: token, buildSessionId, collectorUrl, projectRoot, labId, commonSrcPrefix, slMapping, proxy, rawCoverage. Use token to keep the token out of the deployment package.
--rawCoverage [true|false]
false
Send the metadata that SeaLights needs to process V8 coverage. Required for Lightweight V8 Coverage Mode.
Other
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names. Normally taken from the build session.
completeScan
Reports the end of the build and whether it succeeded. scanned is an alias; buildend is a deprecated name of the same command.
When to use: after all scan commands of a build session, especially for multi-module builds.
--ok
The build succeeded. Pass exactly one of --ok and --failed.
--failed
The build failed.
instrument
Copies the files of --workspacePath to --outputPath and instruments the JavaScript files in the copy for browser coverage. It does not report the build structure.
When to use: to instrument a build that was already scanned, for example once per test environment with its own lab ID. The build must have been scanned with --useRelativeSlMapping; otherwise instrument fails with Build was performed without 'useRelativeSlMapping' flag. To scan and instrument in one step, use scan --instrumentForBrowsers instead.
--workspacePath <path>
-w, --distFolderPath, --distPath, --distributablePath
Required. Directory of the built files to instrument.
--outputPath <path>
-o
Required. Directory for the instrumented copy. Must differ from --workspacePath.
--reduceFileSize / --no-reduceFileSize
on
Instrument without line-level counters, which makes the instrumented files much smaller. --no-reduceFileSize turns it off.
--allowCORS <origins>
page origin only
Accepted, but instrument currently drops the list. To send context propagation headers to other origins, use scan --instrumentForBrowsers --allowCORS.
--projectRoot, --labId, --collectorUrl, --excludeTokenFromBrowserConfig, --allowedDomains, --footprintsMapping, --splitPreambleIntoFile, --preambleFileName, --preambleFileUrl, --toggleBasedBrowserInstrumentation, --skipEsiScripts, --enableOpenTelemetry, --ctxPropagationOnly, --delayShutdownInSeconds, --es6Modules, --babylonPlugins
Same as on scan. instrument takes --enableLineCoverage and --embedCorrectUniqueId from the scan of the build.
mocha
Runs the Mocha installed in your project with the SeaLights Mocha reporter. It collects coverage per test, reports each test result, and skips the tests that Test Impact Analysis does not recommend. Mocha arguments go after --. If slnodejs cannot start (for example, the token is invalid), the tests run without SeaLights.
When to use: for Mocha unit and component tests. See Mocha Tests framework.
--testStage <name>
Unit Tests
Test stage that the results and coverage are reported to.
--labId <id>
build session ID
Lab ID. Without a build session flag, mocha finds the build session from the lab.
--disableTia
--tiaDisabled, --enforceFullRun (deprecated)
false
Run all tests and ignore Test Impact Analysis recommendations. Use for full regression runs.
--testProjectId <id>
Separates test stages with the same name that belong to different teams or products.
--prID <id>
Identifies pull request pipeline runs, so they are kept apart from other runs of the same test stage.
--testGroupId <id>
Test group ID.
--projectRoot <path>
-p
working directory
Use the same project root as the scan.
--es6Modules
false
Collect coverage from ES module code.
--httpServerColoring
false
Attribute coverage of incoming HTTP requests to the test named in their headers.
--httpClientColoring
false
Add the current test to outgoing HTTP requests.
--useBranchCoverage [true|false]
false
Collect branch coverage.
--resolveWithoutHash [true|false]
true
Leave the default.
--useSlNode2 [true|false]
Deprecated; has no effect. Remove it from your commands.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
Options of the SeaLights Mocha reporter (reporter, reportSuites, skipEpilogue) are Mocha reporter options, passed after -- with --reporter-options. See Mocha Tests framework → Reporter options.
run
Runs a Node.js program with the SeaLights test listener, which collects coverage while the program runs. The program and its arguments go after --. If slnodejs cannot start, the program runs without SeaLights.
When to use: to start an application under test (back-end service) with coverage, or to run a test framework that has no SeaLights integration. See Backend Instrumentation (dynamic).
run does not open a test stage. Coverage is attributed to the test stage that is open on the lab (--labId, or the build session ID when no lab ID is given).
--labId <id>
build session ID
Lab ID of the test environment. Use one lab ID per environment, and the same lab ID for all replicas of the service in that environment. Always pass a build session flag too: run cannot find the build session from the lab.
--projectRoot <path>
-p
working directory
Root that file paths are resolved against. Set it to the same project root as the scan, for example when the process starts in another directory.
--es6Modules
false
Collect coverage from an ES modules program ("type": "module").
--forwardSignals
false
Forward SIGTERM and SIGINT to the program, so it shuts down gracefully. Use in containers.
--signalForwardingTimeout <s>
10
Seconds to wait for the program to exit after a forwarded signal, before SIGKILL. Only with --forwardSignals.
--httpServerColoring
false
Attribute coverage of incoming HTTP requests to the test named in their headers. Use for per-test coverage of a service under functional tests.
--httpClientColoring
false
Add the current test to outgoing HTTP requests, so the next service attributes its coverage to the same test. Use in services that call other instrumented services.
--useinitialcolor <true|false>
false
Report coverage that is not attributed to an individual test. Use with test frameworks that have no SeaLights integration, run through run. The flag takes a value: --useinitialcolor true.
--collectorUrl <url>
Send coverage to a SeaLights Collector instead of directly to SeaLights.
--libraries <list>
Comma-separated packages in node_modules to include in coverage, for example --libraries @my-org/shared,my-lib. Use when your own code ships as a package.
--omitFootprintsLeadingSlash
false
Remove a leading / from reported file paths.
--useBranchCoverage [true|false]
false
Collect branch coverage.
--scanDir <path>
-w, --workspacePath, --distFolderPath, --distPath, --distributablePath
Accepted for compatibility; the test listener does not use it. Use --projectRoot to align paths.
--useSlNode2 [true|false]
Deprecated; has no effect.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
openTestStage
Opens a test stage on a lab, so that coverage from all agents on that lab is attributed to it. start and startTestStage are aliases.
When to use: before functional, integration or end-to-end tests run against an application that reports coverage on a lab, and before uploading unit test reports with nycReport and uploadReports.
--testStage <name>
Unit Tests
Name of the test stage.
--labId <id>
build session ID
Lab to open the test stage on. Use the same lab ID as the agents of the application under test. Without a build session flag, the build session is found from the lab.
--testGroupId <id>
Test group ID.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
closeTestStage
Closes a test stage. end and endTestStage are aliases.
When to use: after the tests and the report uploads of a test stage have finished.
--testStage <name>
Close the test stage of this name on the lab. Without it, the oldest open test stage on the lab is closed. Pass it when several test stages can be open on the same lab.
--labId <id>
build session ID
Lab to close the test stage on.
--testGroupId <id>
Test group ID.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
uploadReports
Uploads test result report files (JUnit XML by default).
When to use: to report test results from a test framework that has no SeaLights integration.
--file <paths>
--reportFile
Report files, comma-separated. Pass --file or --filesFolder.
--filesFolder <paths>
--reportFilesFolder
Folders, comma-separated. Every file in the folder is uploaded, whatever its extension, so keep only report files there.
--testStage <name>
Opens a test stage of this name before the upload and closes it after. To add results to a test stage that is already open (for example by openTestStage), leave it out and upload before closeTestStage.
--type <type>
JUnitReport
Report type.
--source <name>
Mocha
Test framework that produced the report.
--hasMoreRequests [true|false]
true
false closes the test stage after the upload.
--labId <id>
build session ID
Lab of the test stage. Without a build session flag, the build session is found from the lab.
--testGroupId <id>
Test group ID.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
nycReport
Uploads an NYC JSON coverage report (coverage-final.json) as the coverage of a test stage.
When to use: for unit tests that already produce NYC (Istanbul) coverage, for example Karma, AVA, Vitest with the Istanbul provider, or Jest without the SeaLights plugin. See Unit Tests.
--report <path>
coverage/coverage-final.json in the working directory
NYC JSON report. Generate it with the NYC json reporter.
--projectRoot <path>
-p
working directory
Root that the absolute paths in the report are resolved against. Set it when the tests ran in another directory than the scan, for example in a container.
--testStage <name>
The command needs an open test stage. --testStage opens one for this upload and closes it after. Leave it out when the test stage is already open.
--labId <id>
build session ID
Lab of the test stage. nycReport cannot find the build session from the lab: also pass a build session flag.
--testGroupId <id>
Test group ID.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
componentUpdate and componentDelete
componentUpdate adds components to an integration build, or updates their versions. componentDelete removes them. Both take the same flags.
When to use: to maintain the list of services that make up an integration build. See Per-Component Update/Delete.
--componentIds <list>
Components separated by , or ;. Each is a build session ID or appName@branch@build. Pass --componentIds or --componentFile.
--componentFile <path>
JSON array. Each item has buildSessionId, or appName with branch and build (branchName and buildName are also accepted). The key appName is case-sensitive; an item without a valid key fails the command.
--appName, --branchName, --buildName
--branch, --build
Application, branch and build names.
dryRun
Scans the code locally and, with --hasNycReport, reads an NYC coverage report and checks that both match. It writes the results to the sl-dry-run-output folder and does not report a build.
When to use: before the first real scan, to check which files are scanned, how source maps resolve, and whether NYC paths match. See dryRun Command: Troubleshooting and Validation.
dryRun needs no token and does not connect to SeaLights, except with --instrumentForBrowsers, which needs a valid token.
--scanDir <path>
-w, --workspacePath, --distFolderPath, --distPath, --distributablePath
Required. Directory to check.
--scm <type>
none
git checks Git paths.
--verbose
false
Print more detail in the summary. Recommended.
--folderDepth <n>
3
Folder depth used when printing method IDs.
--buildScanProjectRoot <path>
working directory
Project root of the scan (scan --projectRoot).
--hasNycReport
false
Also read and check an NYC JSON report.
--report <path>
coverage/coverage-final.json
NYC JSON report to check.
--nycProjectRoot <path>
working directory
Project root of the NYC report (nycReport --projectRoot).
Scan and instrumentation flags
--outputPath, --es6Modules, --babylonPlugins, --excludeFiles, --instrumentForBrowsers, --instrumentationOnly, --excludeSourceMapFiles, the method mapping flags, and the browser instrumentation flags behave as on scan. Pass the same values you use for scan.
Logging
Logging is controlled with environment variables. See Troubleshooting → Turn on logs.
Last updated
Was this helpful?

