> 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/command-reference.md).

# 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/flags-guide.md) and, for browser instrumentation, the [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).

{% hint style="info" %}
`npx slnodejs <command> --help` prints the flags of the version you have installed. When this page and `--help` disagree, `--help` is right for your version.
{% endhint %}

Settings that have no flag (environment variables only, for example `SL_TLS_VERIFY` or `SL_useLeanCoverageListener`) are listed in [Configuration → Environment Variables](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#environment-variables).

## Conventions <a href="#conventions" id="conventions"></a>

* **Flag names are case-insensitive.** `--tokenfile` and `--tokenFile` are the same flag. The examples use the recommended name, which `--help` lists 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.
* **`run` and `mocha` take the program or test arguments after `--`.** Everything after `--` goes to your program or to Mocha. See [Understanding the `--` separator](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/understanding-the-double-dash-separator-in-slnodejs-run-commands.md).
* **A failing command exits with status code 0 by default**, so SeaLights never breaks your pipeline. Add `--failOnError true` to the commands that must fail the pipeline.
* **Token and build session flags are on every command.** They are described once, in [Common flags](#common-flags). `dryRun` accepts them but needs them only with `--instrumentForBrowsers`.

## Commands overview <a href="#commands-overview" id="commands-overview"></a>

| Command                                                   | Aliases                            | Purpose                                                                     | Stage          |
| --------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------- | -------------- |
| [`config`](#config)                                       |                                    | Create a build session ID                                                   | Build          |
| [`prConfig`](#prconfig)                                   |                                    | Create a build session ID for a pull request build                          | Build          |
| [`scan`](#scan)                                           | `build`                            | Scan the build and report its structure; optionally instrument for browsers | Build          |
| [`completeScan`](#completescan)                           | `scanned`, `buildend` (deprecated) | Report the end of the build and its status                                  | Build          |
| [`instrument`](#instrument)                               |                                    | Instrument JavaScript for browser coverage without scanning                 | Build / Deploy |
| [`mocha`](#mocha)                                         |                                    | Run Mocha tests with coverage and Test Impact Analysis                      | Test           |
| [`run`](#run)                                             |                                    | Run a Node.js program (application or test runner) with coverage            | Test           |
| [`openTestStage`](#openteststage)                         | `start`, `startTestStage`          | Open a test stage on a lab                                                  | Test           |
| [`closeTestStage`](#closeteststage)                       | `end`, `endTestStage`              | Close a test stage                                                          | Test           |
| [`uploadReports`](#uploadreports)                         |                                    | Upload test result reports (JUnit XML)                                      | Test           |
| [`nycReport`](#nycreport)                                 |                                    | Upload an NYC JSON coverage report                                          | Test           |
| [`componentUpdate`](#componentupdate-and-componentdelete) |                                    | Add or update components of an integration build                            | Build          |
| [`componentDelete`](#componentupdate-and-componentdelete) |                                    | Remove components from an integration build                                 | Build          |
| [`dryRun`](#dryrun)                                       |                                    | Check a scan and an NYC report locally, without reporting a build           | Setup          |

{% hint style="warning" %}
`jasmine`, `mochaPhantomjs`, `externalReport` and `installBabel` are no longer supported. They are not in `npx slnodejs --help` and do not run any SeaLights logic. For Jasmine, use [`run`](#run) as described in [Other Test Frameworks](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/other-test-frameworks.md).
{% endhint %}

## Common flags <a href="#common-flags" id="common-flags"></a>

These flags are accepted by every command.

| Flag                          | Aliases       | Default                                                                                                      | Description and when to use                                                                                                                                                                                                                                                                                                                    |
| ----------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#tls-and-proxy-issues). |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md).

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs config --tokenFile sltoken.txt --appName my-app --branchName main --buildName "1.0.$BUILD_NUMBER"
```

| Flag                          | Aliases    | Default | Description and when to use                                                                                                                                                                          |
| ----------------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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.                                                   |
| [Common flags](#common-flags) |            |         |                                                                                                                                                                                                      |

## prConfig

Creates a build session ID for a pull request build and writes it to a file, like [`config`](#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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md#pull-request-builds).

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs prConfig --tokenFile sltoken.txt --appName my-app \
  --targetBranch main --latestCommit "$GIT_COMMIT" --pullRequestNumber 42 \
  --repositoryUrl https://github.com/my-org/my-app
```

| Flag                                       | Aliases               | Default | Description and when to use                                      |
| ------------------------------------------ | --------------------- | ------- | ---------------------------------------------------------------- |
| `--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.                             |
| [Common flags](#common-flags)              |                       |         |                                                                  |

## 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md).

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir dist --scmType git
```

Rules:

* A build session can be scanned once. A second scan of the same build session fails, unless each scan has its own `--moduleName`.
* `--outputPath` and `--scanDir` must be different directories.
* With `--dependency` or `--dependenciesFile` (integration build), `--scanDir` and `--scmType` are ignored.
* `--allowCORS` requires `--enableOpenTelemetry`.

### Input and scope

| Flag                         | Aliases                                                                          | Default           | Description and when to use                                                                                                                                                                                                                                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#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

| Flag                               | Aliases        | Default                        | Description and when to use                                                                                                                                               |
| ---------------------------------- | -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md) and in the [Browser Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.md) section.

| Flag                                       | Aliases | Default                 | Description and when to use                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------ | ------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/flags-and-settings-guide.md#togglebasedbrowserinstrumentation). |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md).                                                                                                                           |
| `--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.

| Flag                                                    | Aliases | Default | Description and when to use                                                                                                                                                                    |
| ------------------------------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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

| Flag                        | Aliases | Default | Description and when to use                                                                                                                                                                             |
| --------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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

| Flag                             | Aliases | Default | Description and when to use                                                                                                                                                                                                                                                                                                          |
| -------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/aws-lambda-support.md). |
| `--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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md).                                                        |

### Other

| Flag                                       | Aliases               | Default | Description and when to use                                                 |
| ------------------------------------------ | --------------------- | ------- | --------------------------------------------------------------------------- |
| `--appName`, `--branchName`, `--buildName` | `--branch`, `--build` |         | Application, branch and build names. Normally taken from the build session. |
| [Common flags](#common-flags)              |                       |         |                                                                             |

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

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs completeScan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --ok
```

| Flag                          | Aliases | Default | Description and when to use                                     |
| ----------------------------- | ------- | ------- | --------------------------------------------------------------- |
| `--ok`                        |         |         | The build succeeded. Pass exactly one of `--ok` and `--failed`. |
| `--failed`                    |         |         | The build failed.                                               |
| [Common flags](#common-flags) |         |         |                                                                 |

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

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs instrument --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --workspacePath dist --outputPath sl_dist --labId qa-env
```

{% hint style="warning" %}
`instrument` does not accept `--scanDir`. Use `--workspacePath`.
{% endhint %}

| Flag                                                                                                                                                                                                                                                                                                                                                                         | Aliases                                                       | Default          | Description and when to use                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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`](#browser-instrumentation). `instrument` takes `--enableLineCoverage` and `--embedCorrectUniqueId` from the scan of the build.          |
| [Common flags](#common-flags)                                                                                                                                                                                                                                                                                                                                                |                                                               |                  |                                                                                                                                                            |

## 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/mocha-tests-framework.md).

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" -- --recursive test
```

| Flag                                       | Aliases                                          | Default           | Description and when to use                                                                           |
| ------------------------------------------ | ------------------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------- |
| `--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.                                                                  |
| [Common flags](#common-flags)              |                                                  |                   |                                                                                                       |

Options of the SeaLights Mocha reporter (`reporter`, `reportSuites`, `skipEpilogue`) are Mocha reporter options, passed after `--` with `--reporter-options`. See [Mocha Tests framework → Reporter options](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/mocha-tests-framework.md#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)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/backend-instrumentation-dynamic.md).

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs run --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env -- server.js
```

`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).

| Flag                                       | Aliases                                                                          | Default           | Description and when to use                                                                                                                                                                                                      |
| ------------------------------------------ | -------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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.                                                                                                                                                                                                         |
| `--testStage <name>`                       |                                                                                  | `Unit Tests`      | Does not open a test stage. Open the test stage with [`openTestStage`](#openteststage).                                                                                                                                          |
| `--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.                                                                                                                                                                                             |
| [Common flags](#common-flags)              |                                                                                  |                   |                                                                                                                                                                                                                                  |

## 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`.

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "Integration Tests"
```

| Flag                                       | Aliases               | Default          | Description and when to use                                                                                                                                            |
| ------------------------------------------ | --------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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.                                                                                                                                   |
| [Common flags](#common-flags)              |                       |                  |                                                                                                                                                                        |

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

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "Integration Tests"
```

| Flag                                       | Aliases               | Default          | Description and when to use                                                                                                                                              |
| ------------------------------------------ | --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--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.                                                                                                                                     |
| [Common flags](#common-flags)              |                       |                  |                                                                                                                                                                          |

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

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --file results/unit.xml,results/integration.xml
```

{% hint style="warning" %}
If you repeat `--file` or `--filesFolder`, only the last value is used. To upload several files or folders, pass one comma-separated list.
{% endhint %}

| Flag                                       | Aliases               | Default          | Description and when to use                                                                                                                                                                                   |
| ------------------------------------------ | --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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.                                                                                                                                                                          |
| [Common flags](#common-flags)              |                       |                  |                                                                                                                                                                                                               |

## 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/unit-tests.md).

```bash
echo "<your-agent-token>" > sltoken.txt
npx slnodejs nycReport --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" --report coverage/coverage-final.json
```

| Flag                                       | Aliases               | Default                                                 | Description and when to use                                                                                                                                |
| ------------------------------------------ | --------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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.                                                                                                                       |
| [Common flags](#common-flags)              |                       |                                                         |                                                                                                                                                            |

## 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/build-and-test-execution/integration-build/integration-build-explicit-components-and-versions/per-component-update-delete-java-node.js.md).

```bash
echo "<your-agent-token>" > sltoken.txt
cat > components.json <<'JSON'
[
  { "appName": "billing-service", "branch": "main", "build": "2.3.1" },
  { "buildSessionId": "<component-build-session-id>" }
]
JSON
npx slnodejs componentUpdate --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --componentFile components.json
```

| Flag                                       | Aliases               | Default | Description and when to use                                                                                                                                                                                              |
| ------------------------------------------ | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--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.                                                                                                                                                                                     |
| [Common flags](#common-flags)              |                       |         |                                                                                                                                                                                                                          |

## 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md).

```bash
npx slnodejs dryRun --scanDir dist --verbose
npx slnodejs dryRun --scanDir dist --hasNycReport --report coverage/coverage-final.json --verbose
```

{% hint style="warning" %}
`dryRun` takes `--scm`, not the `--scmType` of `scan`. It accepts unknown flags without a warning, so a misspelled or `scan`-only flag is ignored silently.
{% endhint %}

`dryRun` needs no token and does not connect to SeaLights, except with `--instrumentForBrowsers`, which needs a valid token.

| Flag                            | Aliases                                                                          | Default                        | Description and when to use                                                                                                                                                                                                                                                                 |
| ------------------------------- | -------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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`](#scan). Pass the same values you use for `scan`. |
| [Common flags](#common-flags)   |                                                                                  |                                | Needed only with `--instrumentForBrowsers`.                                                                                                                                                                                                                                                 |

## Logging

Logging is controlled with environment variables. 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).


---

# 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/command-reference.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.
