> 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/node.js-agent/flags-guide.md).

# Flags Guide

The slnodejs flags and settings you decide on: what each does, the problem it solves, how to tell whether you need it, and an example.

This page explains the `slnodejs` flags and environment settings that you choose per setup: what each one does, which problem it solves, how to tell whether you need it, and an example. Browser instrumentation flags have their own guide: [Browser Agent → Flags and Settings Guide](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/flags-and-settings-guide.md). For the complete list with aliases and defaults, see the [Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md).

## Quick reference <a href="#quick-reference" id="quick-reference"></a>

| Setting                                                                        | Solves                                                       | You need it if                                                        |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------- |
| [`--tokenFile`](#tokenfile)                                                    | Token visible in process lists and logs                      | Always (recommended over `--token`)                                   |
| [`--buildSessionIdFile` / `--buildSessionId`](#buildsessionid)                 | Commands do not know which build they belong to              | Always after `config`                                                 |
| [`--failOnError true`](#failonerror)                                           | A failed SeaLights step goes unnoticed                       | A missing scan must fail the pipeline                                 |
| [`--proxy`](#proxy)                                                            | No direct internet access                                    | Outbound traffic goes through a proxy                                 |
| [`SL_TLS_VERIFY`, `SL_CA_FILE`](#tls)                                          | Certificates not verified, or rejected behind TLS inspection | Security requires verification, or a TLS-inspecting proxy is in place |
| [`--overrideServer`](#overrideserver)                                          | Commands must talk to another server than the token's        | A Collector or gateway sits in front of SeaLights                     |
| [`--scanDir`](#scandir)                                                        | Wrong files scanned                                          | Always                                                                |
| [`--projectRoot`](#projectroot)                                                | Coverage paths do not match the scan                         | Scan and runtime start in different directories                       |
| [`--scmType git`](#scmtype)                                                    | No commits or contributors in SeaLights                      | The scan runs in a Git checkout                                       |
| [`--repositoryUrl`, `--scmProvider`, `--scmVersion`, `--commit`](#scm-details) | Wrong or missing links to source                             | No `origin` remote, non-GitHub SCM, or no Git checkout                |
| [`--es6Modules`](#es6modules)                                                  | ES module code not parsed or not covered                     | `"type": "module"`, `.mjs`, or ES module bundles                      |
| [`--babylonPlugins`](#babylonplugins)                                          | Parse errors on JSX or decorators                            | You scan un-transpiled JSX or decorator code                          |
| [`.slignore`, `--excludeFiles`](#exclude)                                      | Tests and generated code in coverage                         | Always worth setting                                                  |
| [`--moduleName`](#modulename)                                                  | Second scan of a build session fails                         | Several folders form one build                                        |
| [`--useModulePrefix`](#usemoduleprefix)                                        | Files of two modules collide                                 | Modules contain files with the same relative paths                    |
| [`--dependency`, `--dependenciesFile`](#dependency)                            | No view of a release made of services                        | You test several services together as one release                     |
| [`--partialBuildMapping`](#partialbuildmapping)                                | Huge build map upload fails                                  | Very large builds                                                     |
| [`--rawCoverage`](#rawcoverage)                                                | Lightweight V8 coverage cannot be processed                  | You use lightweight V8 mode or raw Lambda coverage                    |
| [`--awsConfigure`, `--awsConfigKeysToIgnore`](#awsconfigure)                   | Lambda layer has no configuration                            | AWS Lambda functions                                                  |
| [`--labId`](#labid)                                                            | Coverage lands in the wrong test stage                       | More than one environment, or the tests run elsewhere                 |
| [`--forwardSignals`](#forwardsignals)                                          | Application killed without a clean shutdown                  | Containers, Kubernetes, process managers                              |
| [`--httpServerColoring`](#httpservercoloring)                                  | Back-end coverage not per test                               | Functional tests send test headers and you want per-test coverage     |
| [`--httpClientColoring`](#httpclientcoloring)                                  | Downstream services lose the test identity                   | The service calls other instrumented services                         |
| [`--useinitialcolor true`](#useinitialcolor)                                   | No coverage from an unsupported test runner                  | You run a test framework through `run`                                |
| [`--libraries`](#libraries)                                                    | Your packages in `node_modules` not covered                  | Your code ships as packages                                           |
| [`--collectorUrl`](#collectorurl)                                              | Test environment cannot reach SeaLights                      | Closed networks                                                       |
| [`--testStage`](#teststage)                                                    | Results land in the default test stage                       | Always name test stages                                               |
| [`--disableTia`](#disabletia)                                                  | Tests skipped by Test Impact Analysis                        | Full regression runs                                                  |
| [`--testProjectId`, `--prID`](#testprojectid)                                  | Same test stage name used by different teams or PRs          | Shared test stage names                                               |
| [`--file` list, `--hasMoreRequests`](#uploadreports-flags)                     | Only one report uploaded; test stage closed early            | Several report files, or several upload steps                         |
| [`SL_useLeanCoverageListener`](#sl_useleancoveragelistener)                    | Memory or start-up overhead                                  | Large services where per-test-stage coverage is enough                |
| [`SL_enableChildProcessPatcher`](#sl_enablechildprocesspatcher)                | Worker processes not covered                                 | The program forks processes that run your code                        |
| [`SL_enabled=false`](#sl_enabled)                                              | Need to turn SeaLights off without changing commands         | Environments where coverage must stop temporarily                     |

***

## Authentication and connectivity <a href="#connectivity" id="connectivity"></a>

### `--tokenFile` (vs `--token`) <a href="#tokenfile" id="tokenfile"></a>

* **What it does:** reads the agent token from a file (default `sltoken.txt`).
* **Problem it solves:** a token passed with `--token` is visible in the process list, shell history and CI logs.
* **You need it if:** always. Use `--token` only where you cannot write a file.
* **Example:** `printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt` then `--tokenFile sltoken.txt`.

### `--buildSessionIdFile` / `--buildSessionId` <a href="#buildsessionid" id="buildsessionid"></a>

* **What it does:** tells the command which build session (build) it belongs to.
* **Problem it solves:** without the right build session, coverage and test results attach to another build or are rejected.
* **You need it if:** always after `config`. Use the file within a job (and as a CI artifact between jobs); use the value when you pass the ID as a pipeline variable. `run` and `nycReport` always need one, even with `--labId`.
* **How to tell:** `run` prints `Sealights is disabled, running command without sealights`, or results appear on another build.
* **Example:** `--buildSessionIdFile buildSessionId` or `--buildSessionId "$SL_BSID"`.

### `--failOnError` <a href="#failonerror" id="failonerror"></a>

* **What it does:** `true` makes the command exit with status code 1 when it fails. By default, failures exit with 0.
* **Problem it solves:** a failed `config` or `scan` passes silently, and every later step reports to nothing.
* **You need it if:** the team must notice when SeaLights is not set up for a build. Typically on `config` and `scan`; leave it off on test steps so tests never fail because of SeaLights.
* **Example:** `npx slnodejs scan ... --failOnError true`

### `--proxy` <a href="#proxy" id="proxy"></a>

* **What it does:** sends traffic to SeaLights through an HTTP proxy. The preload script and test listener use `SL_proxy`.
* **You need it if:** the build agents or test environment reach the internet only through a proxy.
* **How to tell:** `curl https://<your-domain>.sealights.co` fails without `--proxy`/`HTTPS_PROXY`; the log shows connection timeouts.
* **Example:** `--proxy http://proxy.example.com:3128`

### `SL_TLS_VERIFY` and `SL_CA_FILE` <a href="#tls" id="tls"></a>

* **What they do:** `SL_TLS_VERIFY=true` verifies TLS certificates of all SeaLights connections, including through a proxy. `SL_CA_FILE` adds a corporate CA (PEM) on top of the defaults.
* **Problem they solve:** by default, connections through a proxy are not verified; with verification on, a TLS-inspecting proxy's certificate is rejected unless its CA is trusted.
* **You need them if:** your security policy requires certificate verification, or your proxy inspects TLS.
* **How to tell:** the log shows `enabling SL_TLS_VERIFY would currently fail for <server>` (verification would fail; you need `SL_CA_FILE`), or `TLS certificate verification for <server> failed`.
* **Example:** `export SL_TLS_VERIFY=true SL_CA_FILE=/etc/ssl/certs/corporate-ca.pem`. Details: [Troubleshooting → TLS and proxy](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#tls-and-proxy-issues).

### `--overrideServer` <a href="#overrideserver" id="overrideserver"></a>

* **What it does:** sends the command's traffic to this server instead of the server named in the token.
* **You need it if:** a SeaLights Collector or an internal gateway must relay CLI traffic.
* **Example:** `--overrideServer https://collector.example.com:16500/api`. Remote configuration takes precedence over this flag.

***

## Build session <a href="#build-session" id="build-session"></a>

### `--appName`, `--branchName`, `--buildName` (`config`) <a href="#config-names" id="config-names"></a>

* **What they do:** identify the application, branch and build.
* **Problem they solve:** SeaLights compares builds of the same application and branch; reused or unstable names break that history.
* **You need them if:** always on `config`. Keep `--appName` stable; make `--buildName` unique per build (CI build number, run ID plus attempt).
* **How to tell:** `Module already exists` errors mean a `--buildName` was reused.

### `prConfig` flags <a href="#prconfig" id="prconfig"></a>

* **What they do:** `--targetBranch`, `--latestCommit`, `--pullRequestNumber`, `--repositoryUrl` create a pull request build session compared against its target branch.
* **You need them if:** the pipeline runs for pull requests and you want pull-request-level analysis. Use `prConfig` instead of `config`.

### `--beControlledVersions` <a href="#becontrolledversions" id="becontrolledversions"></a>

* **What it does:** before creating the session, installs the `slnodejs` version that SeaLights recommends for your account.
* **You need it if:** you want SeaLights (the dashboard) to control the agent version without changing your pipeline.

***

## Scanning <a href="#scanning" id="scanning"></a>

### `--scanDir` <a href="#scandir" id="scandir"></a>

* **What it does:** the folder whose code is scanned.
* **Problem it solves:** coverage is matched to scanned files by path and position; scanning other files than those that run means no match.
* **You need it if:** always (except integration builds). Scan the build output for transpiled or bundled code, the source folder for plain JavaScript.
* **How to tell:** `dryRun --scanDir <dir>` → `included-files.json` lists exactly the files that run.
* **Example:** `--scanDir dist`

### `--projectRoot` <a href="#projectroot" id="projectroot"></a>

* **What it does:** the root that file paths are reported relative to (default: the working directory). Accepted by `scan`, `run`, `mocha`, `nycReport`.
* **Problem it solves:** if `scan` and the running application use different roots, their file paths differ and coverage does not match.
* **You need it if:** the scan runs in one directory and the application or tests in another (a container's `/app`, a sub-folder, a different CI workspace), or an NYC report contains absolute paths from another machine.
* **How to tell:** the agent sends data but coverage stays at 0%; `dryRun --hasNycReport` reports `Nyc Paths` problems.
* **Example:** `npx slnodejs run --projectRoot /app ...` with the scan run from the repository root that contains the same layout.

### `--scmType git` <a href="#scmtype" id="scmtype"></a>

* **What it does:** reports commits and contributors from the local Git repository.
* **Problem it solves:** without it, SeaLights cannot show who changed what, or which changes are untested.
* **You need it if:** the scan runs in a Git checkout. In CI, use a full clone (shallow clones have no history).
* **How to tell:** the build in SeaLights has no commits; in CI, `git log --oneline | wc -l` returns 1.
* **Example:** `--scmType git` (GitHub Actions: `fetch-depth: 0`).

### `--repositoryUrl`, `--scmProvider`, `--scmVersion`, `--commit` <a href="#scm-details" id="scm-details"></a>

* **What they do:** override the repository URL (default: the `origin` remote), the SCM type (`Github` default, `Bitbucket`, `Gitlab`), the on-premises SCM version, and the commit ID.
* **You need them if:** the checkout has no `origin` (or it points to a mirror), you use Bitbucket or GitLab, an on-premises SCM server, or the scan runs outside a Git checkout.
* **How to tell:** links from SeaLights to your code are missing or point to the wrong host.

### `--es6Modules` <a href="#es6modules" id="es6modules"></a>

* **What it does:** on `scan`, parses files as ES modules; on `run` and `mocha`, loads the ES module hook so NYC covers ES module code.
* **Problem it solves:** ES module code is not parsed correctly as classic scripts, and without the hook it is not covered at runtime.
* **You need it if:** `package.json` has `"type": "module"`, the code uses `.mjs`, or the files contain top-level `import`/`export`.
* **How to tell:** the dashboard shows `parsed to AST with the following error(s)` warnings; or `run` collects no coverage from an ES module service.
* **Example:** `npx slnodejs run --es6Modules ... -- server.mjs`. The preload script cannot do this; use `run`.

### `--babylonPlugins` <a href="#babylonplugins" id="babylonplugins"></a>

* **What it does:** extra parser plugins: `jsx`, `decorators-legacy`.
* **You need it if:** you scan code that still contains JSX or decorators (not needed for compiled output).
* **How to tell:** parse-error warnings for `.jsx` files or decorator lines.
* **Example:** `--babylonPlugins jsx,decorators-legacy`

### `.slignore` and `--excludeFiles` <a href="#exclude" id="exclude"></a>

* **What they do:** exclude files from the scan (`.gitignore` syntax).
* **Problem they solve:** tests, mocks, generated code and build tooling distort coverage percentages and slow the scan.
* **You need them if:** almost always. Prefer `.slignore`; `--excludeFiles` has a known issue (see [Configuration → Ignore files](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#ignore-files)).
* **How to tell:** `dryRun` → `included-files.json` contains test or generated files.
* **Example:** `.slignore` with `test/`, `**/*.spec.js`, `coverage/`.

### `--moduleName` <a href="#modulename" id="modulename"></a>

* **What it does:** names a module, so several scans can report parts of one build session.
* **Problem it solves:** a build session can be scanned only once; a second scan fails.
* **You need it if:** one build is made of several folders: a monorepo, client and server of an SSR app, several services released as one.
* **How to tell:** the second `scan` of the same build session fails.
* **Example:** `--scanDir packages/api/dist --moduleName api`, then `--scanDir packages/web/dist --moduleName web`, then `completeScan --ok`.

### `--useModulePrefix` <a href="#usemoduleprefix" id="usemoduleprefix"></a>

* **What it does:** prefixes file paths and method IDs with the module name.
* **You need it if:** two modules contain files with the same relative path (for example both have `src/index.js`), and their coverage collides.

### `--dependency` / `--dependenciesFile` <a href="#dependency" id="dependency"></a>

* **What they do:** create an integration build made of other builds (`appName@branch@build` or build session IDs).
* **You need them if:** you test several separately built services together and want one view of the release. See [Integration Build](https://docs.sealights.io/knowledgebase/setup-and-configuration/build-and-test-execution/integration-build.md).
* **Example:** `--dependency "billing@main@2.3.1;orders@main@5.0.0"`

### `--partialBuildMapping` <a href="#partialbuildmapping" id="partialbuildmapping"></a>

* **What it does:** uploads the build map in chunks of the given number of files.
* **You need it if:** very large builds fail or time out while uploading the build map.
* **Example:** `--partialBuildMapping 500`

### `--rawCoverage` <a href="#rawcoverage" id="rawcoverage"></a>

* **What it does:** sends the metadata SeaLights needs to process V8 coverage.
* **You need it if:** you use [Lightweight V8 Coverage Mode](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md), or raw V8 coverage from the Lambda layer. Without it, lightweight coverage cannot be matched.
* **Example:** `npx slnodejs scan ... --rawCoverage`

### `--awsConfigure` and `--awsConfigKeysToIgnore` <a href="#awsconfigure" id="awsconfigure"></a>

* **What they do:** write an `sl-config.json` into each subdirectory of `--scanDir` for the Lambda layer; leave keys out of it.
* **Problem they solve:** the Lambda layer needs the build session (and optionally lab, Collector, proxy) without you setting every variable on every function.
* **You need them if:** you deploy Node.js Lambda functions. Always add `--awsConfigKeysToIgnore token`, so the token is not packaged in plain text, and set `SL_TOKEN` on the function.
* **Example:** `--awsConfigure --awsConfigKeysToIgnore token`

### `--useBranchCoverage` <a href="#usebranchcoverage" id="usebranchcoverage"></a>

* **What it does:** collects branch coverage in addition to method coverage.
* **You need it if:** your reports or quality gates use branch coverage. SeaLights remote configuration takes precedence.

### Method mapping flags <a href="#method-mapping" id="method-mapping"></a>

`--es6Classes`, `--enrichPrivateMethods`, `--hashIncludeNestedMethods`, `--excludeNestedMethods`, `--sourceHash`, `--enrichByLinesMatch`, `--enrichByMethodRange`, `--recognizeBabelCreateClass`, `--experimentalDeduplicateEnrichedMethodsWithOriginals`, `--autoResolveProjectRoot`.

* **What they do:** change how methods are identified and matched to your sources.
* **You need them if:** SeaLights support asks you to, after looking at your build. Signals that lead there: methods reported with wrong names or duplicated, many methods shown as modified although the code did not change, or classes compiled by Babel or TypeScript not matched.
* **Important:** several of them change method IDs. Turning one on or off makes SeaLights report many methods as modified once. Keep them the same for every build.

***

## Running the application or tests (`run`, `mocha`, preload) <a href="#runtime" id="runtime"></a>

### `--labId` <a href="#labid" id="labid"></a>

* **What it does:** the lab (test environment) the agent reports coverage for. Coverage goes to the test stage open on that lab.
* **Problem it solves:** without it, the lab is the build session ID. Two environments of the same build, or a test runner that opens its test stage on a named lab, do not match.
* **You need it if:** the application runs in a shared or named test environment, more than one environment runs the build, or the tests run on another machine and open their test stage on a lab.
* **How to tell:** the agent appears in the Agent Monitor, but the test stage gets no coverage; the test runner uses a lab ID the agent does not.
* **Example:** `npx slnodejs run --labId qa-env ...` (preload: `SL_labId=qa-env`). Use the same lab ID for all services and replicas of one environment.

### `--forwardSignals` and `--signalForwardingTimeout` <a href="#forwardsignals" id="forwardsignals"></a>

* **What they do:** forward `SIGTERM`/`SIGINT` from `slnodejs` to your program, and wait up to the timeout (default 10 seconds) before `SIGKILL`.
* **Problem they solve:** without forwarding, stopping the container stops `slnodejs` but your program gets no signal: no graceful shutdown.
* **You need them if:** the service runs in a container, Kubernetes, or a process manager that stops it with signals.
* **How to tell:** the service does not log its shutdown when the container stops, or stops only after the platform's kill timeout.
* **Example:** `npx slnodejs run --forwardSignals ... -- server.js`. The preload script does not forward signals.

### `--httpServerColoring` <a href="#httpservercoloring" id="httpservercoloring"></a>

* **What it does:** reads the test identity from incoming HTTP request headers and attributes the coverage of each request to that test.
* **Problem it solves:** without it, the coverage of a service under functional tests is attributed to the test stage only, not to individual tests, which limits Test Impact Analysis for those tests.
* **You need it if:** functional tests (with a SeaLights plugin, or a browser front end with context propagation) call this service, and you want per-test coverage.
* **How to tell:** test stage coverage exists, but per-test coverage for API or E2E tests is empty.
* **Example:** `npx slnodejs run --httpServerColoring --labId qa-env ... -- server.js`. Only with `run` or `mocha`; the preload script cannot turn it on. Not available in lightweight V8 mode.

### `--httpClientColoring` <a href="#httpclientcoloring" id="httpclientcoloring"></a>

* **What it does:** adds the current test identity to outgoing HTTP requests.
* **You need it if:** this service calls other instrumented services during tests, and they should attribute their coverage to the same test.
* **Example:** `npx slnodejs run --httpServerColoring --httpClientColoring ... -- gateway.js`

### `--useinitialcolor true` <a href="#useinitialcolor" id="useinitialcolor"></a>

* **What it does:** reports coverage that is not attributed to an individual test.
* **Problem it solves:** a test runner started with `run` has no SeaLights integration, so no test is identified and its coverage is otherwise not reported.
* **You need it if:** you run a test framework (Jasmine, a custom runner) through `slnodejs run`. Not for application servers.
* **Example:** `npx slnodejs run --useinitialcolor true ... -- node_modules/jasmine/bin/jasmine.js`. The flag takes a value.

### `--libraries` <a href="#libraries" id="libraries"></a>

* **What it does:** includes the listed packages from `node_modules` in coverage.
* **Problem it solves:** code under `node_modules` is not covered by default; internal packages installed there (monorepo workspaces, shared company packages) get no coverage.
* **You need it if:** part of your own code is consumed from `node_modules`, and you scanned it.
* **Example:** `--libraries @my-org/shared,@my-org/billing-core`

### `--collectorUrl` <a href="#collectorurl" id="collectorurl"></a>

* **What it does:** sends coverage to a SeaLights Collector instead of directly to SeaLights (preload: `SL_collectorUrl`).
* **You need it if:** the test environment cannot reach SeaLights directly.

### `--es6Modules`, `--projectRoot` <a href="#runtime-es6-projectroot" id="runtime-es6-projectroot"></a>

See [`--es6Modules`](#es6modules) and [`--projectRoot`](#projectroot) above; the same reasoning applies at runtime.

### `--omitFootprintsLeadingSlash` <a href="#omitfootprintsleadingslash" id="omitfootprintsleadingslash"></a>

Removes a leading `/` from reported file paths. Use it only when SeaLights support identifies a leading-slash path mismatch.

***

## Test stages and reports <a href="#test-stages-and-reports" id="test-stages-and-reports"></a>

### `--testStage` <a href="#teststage" id="teststage"></a>

* **What it does:** names the test stage (`Unit Tests` by default on `mocha`, `openTestStage`).
* **Problem it solves:** with the default, different kinds of tests mix in one test stage.
* **You need it if:** always: name each test stage after the kind of tests (`Unit Tests`, `API Tests`, `E2E Tests`). On `closeTestStage`, pass it when several test stages can be open on the same lab.

### `--disableTia` (`mocha`) <a href="#disabletia" id="disabletia"></a>

* **What it does:** runs all tests, ignoring Test Impact Analysis recommendations.
* **You need it if:** a run must be complete, for example nightly or release regression, or to establish a baseline.
* **How to tell:** fewer tests ran than exist, and that is not wanted for this run.

### `--testProjectId` and `--prID` (`mocha`) <a href="#testprojectid" id="testprojectid"></a>

* **What they do:** `--testProjectId` separates test stages with the same name from different teams or products; `--prID` separates pull request runs from other runs of the same test stage.
* **You need them if:** several teams use the same test stage name for the same application, or pull request pipelines run the same test stage as the main branch.

### `uploadReports` flags <a href="#uploadreports-flags" id="uploadreports-flags"></a>

* **`--file` / `--filesFolder`:** pass several files or folders as one comma-separated list; a repeated flag keeps only its last value.
* **`--testStage`:** opens and closes a test stage just for this upload. Leave it out when the test stage is already open.
* **`--hasMoreRequests false`:** closes the test stage after the upload. Leave the default (`true`) when more uploads follow.
* **`--type`, `--source`:** describe the report (default JUnit, Mocha). Change `--type` only for other report types, for example `commitLog`.

### `nycReport --projectRoot` <a href="#nycreport-projectroot" id="nycreport-projectroot"></a>

* **You need it if:** the NYC report was created in another directory or machine than the scan, so its absolute paths do not resolve.
* **How to tell:** `dryRun --hasNycReport --report coverage/coverage-final.json` reports `Nyc Paths` problems.

***

## Environment settings <a href="#environment-settings" id="environment-settings"></a>

### `SL_useLeanCoverageListener` <a href="#sl_useleancoveragelistener" id="sl_useleancoveragelistener"></a>

* **What it does:** collects coverage from Node.js V8 coverage instead of NYC instrumentation.
* **Problem it solves:** NYC instruments code in memory; large services can run out of memory, start slowly or run tests slower.
* **You need it if:** the service shows memory or start-up problems with the agent, runs on Node.js later than 20.6.0, and coverage per test stage is enough.
* **How to tell:** memory or start time increase noticeably when the agent is added; `JavaScript heap out of memory` with the agent only.
* **Example:** scan with `--rawCoverage`, then `SL_useLeanCoverageListener=true npx slnodejs run ...`. See [Lightweight V8 Coverage Mode](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md).

### `SL_enableChildProcessPatcher` <a href="#sl_enablechildprocesspatcher" id="sl_enablechildprocesspatcher"></a>

* **What it does:** starts the agent in Node.js child processes the program spawns. In lightweight V8 mode, makes child processes write coverage at the interval.
* **You need it if:** the program forks workers that run your code (`cluster`, `child_process.fork`, test runners with worker processes such as Jest).
* **How to tell:** coverage covers only the parent process's code; worker code shows 0%.
* **Example:** `SL_enableChildProcessPatcher=true npx slnodejs run ...`

### `SL_useIstanbul` <a href="#sl_useistanbul" id="sl_useistanbul"></a>

Uses the Istanbul engine instead of NYC. Use it only when SeaLights support asks you to.

### `SL_enabled` <a href="#sl_enabled" id="sl_enabled"></a>

* **What it does:** `false` makes the test listener collect and send nothing, while the program runs normally.
* **You need it if:** you want to turn SeaLights off in an environment without changing the start command or image.

### `SL_newUniqueId` <a href="#sl_newuniqueid" id="sl_newuniqueid"></a>

Uses the newer method ID format. Use it only when SeaLights support asks you to, and set the same value for the scan and the test listener.

### `SL_httpTimeout`, `SL_httpMaxAttempts`, `SL_httpAttemptInterval` <a href="#http-retries" id="http-retries"></a>

* **You need them if:** connections to SeaLights are slow or flaky (timeouts in the log), for example over a congested proxy.
* **Example:** `SL_httpTimeout=60000 SL_httpMaxAttempts=5`

### `SL_acceptAllRemoteParams` <a href="#sl_acceptallremoteparams" id="sl_acceptallremoteparams"></a>

* **What it does:** `false` applies SeaLights remote configuration only to the settings it configures by design.
* **You need it if:** a flag you pass is overridden by remote configuration and you need your value to win. Talk to SeaLights support first.

### Logging <a href="#logging" id="logging"></a>

`NODE_DEBUG=sl,sl-file` and `SL_LOG_LEVEL=debug` when you troubleshoot. See [Troubleshooting → Turn on logs](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#turn-on-logs).

***

## Remaining flags <a href="#remaining-flags" id="remaining-flags"></a>

These rarely need a decision:

| Flag                                                        | Use it when                                                                                |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `--compressSlMapping`                                       | The build map upload is large and slow. SeaLights can also set it remotely.                |
| `--scanDotFolders`                                          | Code you want scanned lives in a folder whose name starts with a dot (skipped by default). |
| `--recursive`                                               | Leave the default (`true`).                                                                |
| `--sendContributors false`                                  | Contributor details must not be sent.                                                      |
| `--jobName`, `--logsUrl`                                    | You want the CI job name and a link to the CI logs shown with the build.                   |
| `--testGroupId`                                             | SeaLights support asks you to group test runs.                                             |
| `--skipUpgrade`                                             | The agent must not try to upgrade itself.                                                  |
| `--newInstrumenter`, `--resolveWithoutHash`, `--useBabylon` | Leave the defaults.                                                                        |
| `--useSlNode2`, `--enforceFullRun`                          | Deprecated. Remove `--useSlNode2`; use `--disableTia` instead of `--enforceFullRun`.       |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/flags-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
