Command Reference

Legacy Alias Deprecation Notice

Starting with NodeJS Agent 6.2.1, 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.

NodeJS Agent — Command Reference

Generating a Session ID (`config`)

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

##Minimum required CLI parameters
npx slnodejs config \
  --token <token> \
  --appName <app-name> \
  --branchName <branch> \
  --buildName <build>

All CLI Parameters

CLI Parameter

Legacy Alias

Description

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--appName

--appname

Name of the application.

--branchName

--branch

The source branch of the application.

--buildName

--build

The build label of the current build.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--beControlledVersions

--becontrolledversions

Updates the agent to the version defined by the backend configuration (Default: false).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

Scanning a Build (`scan`)

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

--token

Access token generated from the SeaLights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

Session ID of configuration created.

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--appName

--appname

Name of the application.

--branchName

--branch

The source branch of the application.

--buildName

--build

The build label of the current build.

--scanDir

--workspacePath, --distFolderPath, --distPath, --distributablePath, -w

Path to the source workspace where the source code exists.

--outputPath

-outputpath

Folder to generate the instrumented JS files in when using the instrumentForBrowsers parameter.

--excludeFiles

--excludedpaths

Comma-separated list of files to exclude from scan.

Supports wildcards (* is any string, ? is any character). For example: '*-with-dependencies.jar, bad-bad?.war, *-source.jar'

--labId

--labid

Unique ID for a set of test labs in case multiple labs are running simultaneously or for an Integration Build. This needs to be done during the instrumentation process when using the instrumentForBrowsers option.

--useModulePrefix

Add uniqueModuleId as prefix (if exists) to uniqueId and files path (Default: false).

--jobName

Name of Jenkins job.

--logsUrl

Path to Jenkins log folder.

--projectRoot

Path to the root of the project. Usually where the src folder resides.

--recursive

Enables recursive scan behavior (Default: true).

--scanDotFolders

Includes folders starting with . during scan and dryRun commands.

--partialBuildMapping

Splits build mapping into chunks with the specified number of files.

--useRelativeSlMapping

Uses paths relative to the workspace path (--scanDir) in sl-mapping.

--compressSlMapping

Compresses sl-mapping file before upload.

--moduleName

--uniqueModuleId

Unique module identifier. Value should remain consistent between runs.

--autoResolveProjectRoot

Automatically resolves project root during runtime. When set to true additional data will be appended to the end of the scanned code, which will be used to resolve the project root when running with a test listener (Default: false).

--instrumentForBrowsers

Instrument the javascript files for providing browser front-end coverage information. Must be used with the --outputPath parameter.

--instrumentationOnly

Only instrument the javascript files, without sending the build information to the SeaLights server (i.e. skip the build scan). This parameter must be used in addition to the --instrumentForBrowsers parameter.

--toggleBasedBrowserInstrumentation

Once enabled the browser agent will create separate instrumented files and keep the original files intact. If the preamble file is not found, the original files will be loaded in the browser (Default: false).

--ctxPropagationOnly

Enable only context propagation without performing any additional browser agent instrumentation (Default: false).

--enableOpenTelemetry

Enable open-telemetry instrumentation when working with the browser test listener (Default: false).

--allowCORS

Comma-separated origins allowed for header propagation (* to enable propagation everywhere). Defaults to current origin only. --enableOpenTelemetry must be true for this option.

--allowedDomains

Comma-separated list of domains where the browser agent should load. If empty string is passed, this option is disabled and agent is loaded for all domains (can be used to overwrite env var or remote config). In scan and dryRun commands --instrumentForBrowsers must be used for this to take effect.

--delayShutdownInSeconds

Shutdown time in seconds for the browser agent (Default: 30).

--excludeTokenFromBrowserConfig

Exclude the browser agent token from the browser configuration file (Default: false).

--rawCoverage

Generates metadata required for processing coverage from v8 lightweight agent (Default: false).

--es6Modules

Enables ES6 module handling during scan or run (Default: false).

--es6Classes

Enables ES6 class adjustments during scan. Use it when you scan ts classes that later transpiled to es6 classes.

--enrichPrivateMethods

Enriches methods with accessibility modifiers.

--hashIncludeNestedMethods

Includes nested anonymous methods in hash calculation. First activation of this CLI parameter can cause false-positive code changes.

--excludeNestedMethods

Excludes nested methods from build mapping. First activation of this CLI parameter can cause false-positive code changes.

--enableLineCoverage

Enables line-level coverage mapping (Default: false).

--useBranchCoverage

Enables branch coverage collection (Default: false).

--sourceHash

Generates method hash from source files instead of generated code.

--embedCorrectUniqueId

Embeds unique ID mapping into instrumented files (Default: false).

--resolveWithoutHash

Resolves mappings without using hashes (Default: true).

--newInstrumenter

Uses sl-istanbul-lib-instrument instead of istanbul-lib-instrument (Default: true).

--useBabylon

Uses Babylon parser for scanning files (Default: true).

--babylonPlugins

Values:

decorators-legacy - when there are decorators in the code.
jsx - for React applications.

--footprintsMapping

Determines where browser footprints are resolved (agent or server). Default: agent.

--enrichByLinesMatch

-l

Enables experimental method matching algorithm.

--enrichByMethodRange

Matches methods using original method range positions. Implicitly sets recognizeBabelCreateClass on (Default: false).

--experimentalDeduplicateEnrichedMethodsWithOriginals

Removes duplicated methods from the build map (Default: false).

--recognizeBabelCreateClass

Improves recognition of Babel _createClass calls, even with code minification (Default: false).

--preferSourceMapFromFile

Gives precedence to file-based source maps over inline source maps (Default: false).

--excludeSourceMapFiles

(Optional) During files instrumentation step, this option explicits what to do with *.js.map files in the --scanDir and --outputPath folders:

none - Do nothing and copy *.js.map files as is to the --outputPath folder.
skipCopy - Do not copy the *.js.map files from --scanDir into --outputPath folder.
skipAndDelete - Skip copy of *.js.map files and delete them from the --scanDir.

--skipInstrumentingFilesWithoutSourceMap

Skip instrumenting files without source map (Default: false).

--splitPreambleIntoFile

Moves instrumentation config into a separate file.

Important: customer is responsible to make this file non-cacheable and accessible from the browser.

Usage is --splitPreambleIntoFile to use (not --splitPreambleIntoFile true).

--preambleFileName

Used together with --splitPreambleIntoFile to define a custom preamble file name.

--preambleFileUrl

Used together with --preambleFileName to define a custom URL (Default: "" which equals to root, you can pass like https://example.com/a/b/c or relative like a/b/c).

Important: Only use this if you need a different server than the one used for the instrumented files.
Important: actual URL will be {preambleFileUrl}/{preambleFileName}.

--awsConfigure

Creates sl-config files for AWS Lambda layer integration.

--awsConfigKeysToIgnore

Comma-separated list of AWS config keys to ignore. Supported values are: token, buildSessionId, collectorUrl, projectRoot, labId, commonSrcPrefix, slMapping, proxy, rawCoverage.

--scmType

--scm

Source control used

Current options are: git, none.

--scmProvider

--scmprovider

The provider name of your Source Control Management (SCM) tool. Values: Github, Bitbucket and Gitlab (Default is Github).

--repositoryUrl

--scmbaseurl

The URL to the repository which contains the code.

If not provided, the url of the remote GIT origin will be used.

Example: https://my.bitbucket.com/projects/ABCD/repos/XYZ/browse/A1

--scmVersion

--scmversion

The version of your Source Control Management (SCM) tool. If left blank, cloud version is assumed. Otherwise, specify the version of your on-premise server.

--commit

Commit ID, as provided by the SCM.

--dependency

Project dependencies. Format: semicolon:separated list of AppName@BranchName@BuildName.

--dependenciesFile

-d

Path to JSON file containing dependency definitions. Format: [{"appName":"","branchName":"","buildName":"","buildSessionId":""}.

--sendContributors

Sends contributor details for advanced committer reports and features.

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--collectorUrl

--collectorurl

The URL to Sealights collector used to collect footprints from browser environment (Format: https://<collectorIP>:<collectorPort>/api).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

--quiet

Suppresses console feedback messages only. Does not suppress log output when logging is configured to print to the console (Default: false).

Running a local validation (`dryRun`)

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

All CLI Parameters

CLI Parameter

Description

Equivalent command flag

--verbose

Prints additional information in the command summary output. Default: false.

--folderDepth

Folder depth used when printing unique IDs in the dry run output. Default: 3.

--useBranchCoverage

Collect branch coverage during validation. Default: true.

--help

Show help and exit.

Build scanning validation

--scanDir

Path to the build output to validate.

scan --scanDir

--scmType

Source control used. Current options are git and none.

scan --scmType

--instrumentForBrowsers

Use browser instrumentation logic during validation.

instrument (or scan --instrumentForBrowsers)

--es6Modules

Enable ES module parsing during validation. Default: false.

scan --es6Modules

--babylonPlugins

List of non-default Babylon parser plugins, separated by commas.

decorators-legacy — use when the code contains decorators.
jsx — use for React applications.

scan --babylonPlugins

--excludedPaths

Comma-separated list of excluded path glob patterns.

scan --excludePaths

--outputPath

Optional output path for instrumentation.

scan --outputPath

--buildScanProjectRoot

Root directory used to resolve original source files from source maps. Default: current working directory.

scan --projectRoot

Unit test coverage validation

--hasNycReport

Enable validation of an NYC coverage report in JSON format. Default: false.

nycReport

--nycProjectRoot

Root directory used to resolve NYC report paths. Default: current working directory.

nycReport --projectRoot

--report

Path to the NYC JSON report. Default: <current working directory>/coverage/coverage-final.json.

nycReport --report

Ending a Multi-Module Build (`buildend`)

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

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--ok

Indicates a successful build.

--failed

Indicates a failed build.

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

Instrumenting a Front-End Build (`instrument`)

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

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--labId

--labid

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--scanDir

--workspacePath, --distFolderPath, --distPath, --distributablePath, -w

Path to the source workspace where the source code exists.

--outputPath

--outputpath

Folder to generate the instrumented JS files in when using the instrumentForBrowsers parameter.

--projectRoot

Path to the root of the project. Usually where the src folder resides.

--toggleBasedBrowserInstrumentation

--ctxPropagationOnly

Enable only context propagation without performing any additional browser agent instrumentation (Default: false).

--collectorUrl

--collectorurl

The URL to Sealights collector used to collect footprints from browser environment (Format: https://<collectorIP>:<collectorPort>/api).

--enableOpenTelemetry

Enable open-telemetry instrumentation when working with the browser test listener (Default: false).

--allowCORS

Comma-separated origins allowed for header propagation (* to enable propagation everywhere). Defaults to current origin only. --enableOpenTelemetry must be true for this option.

--allowedDomains

--excludeTokenFromBrowserConfig

Exclude the browser agent token from the browser configuration file (Default: false).

--delayShutdownInSeconds

Shutdown time in seconds for the browser agent (Default: 30 seconds).

--es6Modules

Enables ES6 module handling during scan or run (Default: false).

--babylonPlugins

Values:

decorators-legacy - when there are decorators in the code.
jsx - for React applications.

--footprintsMapping

Determines where browser footprints are resolved (agent or server). Default: agent.

--splitPreambleIntoFile

Moves instrumentation config into a separate file.

Important: customer is responsible to make this file non-cacheable and accessible from the browser.

Usage is --splitPreambleIntoFile to use (not --splitPreambleIntoFile true).

--preambleFileName

Used together with --splitPreambleIntoFile to define a custom preamble file name.

--preambleFileUrl

Used together with --preambleFileName to define a custom URL (Default: "" which equals to root, you can pass like https://example.com/a/b/c or relative like a/b/c).

Important: Only use this if you need a different server than the one used for the instrumented files.
Important: actual URL will be {preambleFileUrl}/{preambleFileName}.

--no-reduceFileSize

Optimizes instrumented file size.

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

Running Backend Server (`run`)

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

Example of command:

Note the ./server in the --workspacePath refers to ./server/app.js in the above example.

All CLI Parameters

CLI Parameter

Legacy Alias

Description

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--appName

--appname

Name of the application.

--branchName

--branch

The build label of the current build.

--buildName

--build

The build label of the current build.

--labId

--labid

--testStage

--teststage

'integration tests', 'regression'). The default will be 'Unit Tests'.

--useBranchCoverage

Enables branch coverage collection (Default: false).

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--collectorUrl

--collectorurl

The URL to Sealights collector used to collect footprints from browser environment (Format: https://<collectorIP>:<collectorPort>/api).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--scanDir

--workspacePath, --distFolderPath, --distPath, --distributablePath, -w

Path to the source workspace where the source code exists.

--outputPath

--outputpath

Folder to generate the instrumented JS files in when using the instrumentForBrowsers parameter.

--projectRoot

Path to the root of the project. Usually where the src folder resides.

--es6Modules

Enables ES6 module handling during scan or run (Default: false).

--httpServerColoring

Enables server-side coloring propagation (Default: false).

--httpClientColoring

Enables client-side coloring propagation (Default: false).

--useInitialColor

--useinitialcolor

Enables generic mode for unsupported test frameworks (Default: false).

--libraries

Comma-separated list of Node modules to include in coverage. CSV format: --libraries=@socket.io,agent-base,chokidar.

--omitFootprintsLeadingSlash

Removes leading slash from footprint paths if present (Default: false).

--forwardSignals

Enables signal forwarding for graceful shutdown in containerized environments. When enabled, termination signals (SIGTERM, SIGINT, etc.) are properly forwarded to the child application process (Default: false).

--signalForwardingTimeout

Timeout in seconds before forcefully terminating child process after signal forwarding (Default: 10).

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

Updating/deleting a Component from an Integration Build (`componentUpdate` or `componentDelete`)

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

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--appName

--appname

Name of the application.

--branchName

--branch

The source branch of the application.

--buildName

--build

The build label of the current build.

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--componentIds

--componentids

A list of comma-separated components build session ids (BSIDs).

--componentFile

--componentfile

A path to a json file. Format: [{"appname":"","branch":"","build":"","buildSessionId":""},{...}]. Every entry may include appName+branchName+buildName or buildSessionId.

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

Test Listener - Opening a Test Stage (`start`)

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

The buildSessionId and buildSessionIdFile parameters are deprecated for test-runner commands. Use labId instead. These parameters remain supported only for unit-test runners that execute the build's code directly (e.g. Mocha, Karma, AVA).

All CLI Parameters

CLI Parameter

Legacy Alias

Description

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--labId

--labid

--testStage

--teststage

Name of the test stage.

--testGroupId

--testgroupid

The test group id.

--appName

--appname

Name of the application.

--branchName

--branch

The source branch of the application.

--buildName

--build

The build label of the current build.

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--overrideServer

--overrideserver

Overrides the server URL used by the agent for connectivity. Example use case: using the Collector as a proxy.

--componentIds

--componentids

A list of comma-separated components build session ids (BSIDs).

--componentFile

--componentfile

A path to a json file. Format: [{"appname":"","branch":"","build":"","buildSessionId":""},{...}]. Every entry may include appName+branchName+buildName or buildSessionId.

--proxy

Address of proxy to run connection through.

--help

Show Help message and exit.

Test Listener - Uploading Report Files (`uploadReports`)

Report files must be JUnit style XML reports.

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

--token

Access token generated from the Sealights server.

--tokenFile

--tokenfile

Path to file containing access token generated from the SeaLights server.

--buildSessionId

--buildsessionid

(Optional) A user provided session ID (case-sensitive).

--buildSessionIdFile

--buildsessionidfile

Path to file containing the Session ID of configuration created.

--labId

--labid

--testStage

--teststage

Name of the test stage.

--appName

--appname

Name of the application.

--branchName

--branch

The source branch of the application.

--buildName

--build

The build label of the current build.

--failOnError

--failbuild

Flag indicating whether the command should exit with status code 1 if the command fails (Default: false).

--skipUpgrade

--skipupgrade

Prevents the agent from attempting automatic upgrades (Default: false).

--overrideServer

Good evening

NodeJS Agent — Command Reference

Generating a Session ID (config)

All CLI Parameters

Scanning a Build (scan)

All CLI Parameters

Running a local validation (dryRun)

All CLI Parameters

Ending a Multi-Module Build (buildend)

All CLI Parameters

Instrumenting a Front-End Build (instrument)

All CLI Parameters

Running Backend Server (run)

All CLI Parameters

Updating/deleting a Component from an Integration Build (componentUpdate or componentDelete)

All CLI Parameters

Test Listener - Opening a Test Stage (start)

All CLI Parameters

Test Listener - Uploading Report Files (uploadReports)

All CLI Parameters

Generating a Session ID (`config`)

Scanning a Build (`scan`)

Running a local validation (`dryRun`)

Ending a Multi-Module Build (`buildend`)

Instrumenting a Front-End Build (`instrument`)

Running Backend Server (`run`)

Updating/deleting a Component from an Integration Build (`componentUpdate` or `componentDelete`)

Test Listener - Opening a Test Stage (`start`)

Test Listener - Uploading Report Files (`uploadReports`)