# Command Reference

### Agent Files <a href="#agent-files" id="agent-files"></a>

There are two agent files

* Build Scanner - sl-build-scanner.jar
* Test Listener - sl-test-listener.jar

Download them from: <https://agents.sealights.co/sealights-java/sealights-java-latest.zip>

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

### Creating a session ID <a href="#inlineextension-creating-a-session-id" id="inlineextension-creating-a-session-id"></a>

#### Standard Session ID <a href="#standard-session-id" id="standard-session-id"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-build-scanner.jar -config {-token <arg> | -tokenfile <arg>} -appname <arg> -branchname <arg> -buildname <arg> -pi <arg> [-pe <arg>] [-buildsessionid <arg>] [-proxy <arg>] [-buildsessionidfile <arg>]
```

{% endcode %}

<table><thead><tr><th width="247.53125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing access token generated from the SeaLights server</td></tr><tr><td><code>appname</code></td><td>Name of the application</td></tr><tr><td><code>branchname</code></td><td>The source branch of the application</td></tr><tr><td><code>buildname</code></td><td>The build label of the current build</td></tr><tr><td><code>pi, packagesincluded</code></td><td><p>Comma-separated list of packages to include in scan</p><p>Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world'</p></td></tr><tr><td><code>pe,packagesexcluded</code></td><td><p>Comma-separated list of packages to exclude from scan</p><p>Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world'</p></td></tr><tr><td><code>buildsessionid</code></td><td>Optional: A user provided session ID. (This ID must be under 40 characters length).</td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to a file to save the build session id in. Default: <code>buildSessionId.txt</code></td></tr><tr><td><code>quiet</code></td><td>Suppresses console feedback messages only. Does not suppress log output when logging is configured to print to the console. The default value is <code>false</code>.</td></tr></tbody></table>

#### Pull Request Session ID <a href="#pull-request-session-id" id="pull-request-session-id"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-build-scanner.jar -prConfig {-token <arg> | -tokenfile <arg>} -appname <arg> -targetBranch <arg> -latestCommit <arg> -pullRequestNumber <arg> -repoUrl <arg> -pi <arg> [-pe <arg>] [-proxy <arg>] [-buildsessionidfile <arg>]
```

{% endcode %}

<table><thead><tr><th width="250.4375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing access token generated from the SeaLights server</td></tr><tr><td><code>appname</code></td><td>Name of the application</td></tr><tr><td><code>targetBranch</code></td><td>The branch to which this PR will be merged into (already reported to SeaLights)</td></tr><tr><td><code>latestCommit</code></td><td>The full SHA of the last commit made to the Pull Request</td></tr><tr><td><code>pullRequestNumber</code></td><td>The number assigned to the Pull Request from the source control</td></tr><tr><td><code>repoUrl</code></td><td>The pull request URL for the PR to be scanned, up until the section before the <code>pullRequestNumber</code> value</td></tr><tr><td><code>pi, packagesincluded</code></td><td>Comma-separated list of packages to include in scan. Supports wildcards (* = any string, ? = any character). For example: <code>'com.example.* ,io.*.demo, com.?ello.world'</code></td></tr><tr><td><code>pe,packagesexcluded</code></td><td>Comma-separated list of packages to exclude from scan. Supports wildcards (* = any string, ? = any character). For example: <code>'com.example.* ,io.*.demo, com.?ello.world'</code></td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to a file to save the build session id in. Default: <code>buildSessionId.txt</code></td></tr></tbody></table>

### Scanning a build <a href="#inlineextension-scanning-a-build" id="inlineextension-scanning-a-build"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-build-scanner.jar -scan {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} [-workspacepath <arg>] [-r] [-baseSourceFolder <arg>] [-componentfile <arg>] [-enableNoneZeroErrorCode] [-fe <arg>] [-fi <arg>] [-moduleName <arg>] [-npf | -pfn <arg>] [-pathToMetaJson <arg>] [-proxy <arg>] [-scmProvider <arg>] [-scmBaseUrl <arg>] [-scmVersion <arg>] [-scm {git|none}] [-customFilterFile <arg>]
```

{% endcode %}

<table><thead><tr><th width="252.81640625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>buildsessionid</code></td><td>Session ID of configuration created</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to file containing the Session ID of configuration created</td></tr><tr><td><code>workspacepath</code></td><td>Path to the source workspace</td></tr><tr><td><code>r, recursive</code></td><td>Recursive search all folders under the workspace path</td></tr><tr><td><code>baseSourceFolder</code></td><td>Relative path from user.dir to the workspace (specify the relative path from the .git folder up to com) Example: <em>src/java</em></td></tr><tr><td><code>componentfile</code></td><td>A path to a json file that is in the following format:<br><code>[{"appName":"","branch":"","build":""}, {...}]</code><br>or<br><code>[{"buildSessionId":"", {...}]</code></td></tr><tr><td><code>enableNoneZeroErrorCode</code></td><td>Exit with an error code if an error is encountered</td></tr><tr><td><code>fe, filesexcluded</code></td><td><p>Comma-separated list of files to exclude from scan</p><p>Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.jar , bad-bad?.war, *-source.jar'</p><p>use comma separated file names or paths like "SpecificFileName1.class,specificFileName2.class" OR "some/sub/folder/*Test.class,another/folder/*/resources/*"</p><p><strong>Don’t use</strong> dot separated packages such as <code>*.ms.*.gateways.mappers.implementation.MapResource.class</code></p></td></tr><tr><td><code>fi, filesincluded</code></td><td><p>Comma-separated list of files to include in scan</p><p>Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.jar ,</p><p>use comma separated file names or paths like "SpecificFileName1.class,specificFileName2.class" OR "some/sub/folder/*Test.class,another/folder/*/resources/*"</p><p><strong>Don’t use</strong> dot separated packages such as <code>*.ms.*.gateways.mappers.implementation.MapResource.class</code></p></td></tr><tr><td><code>moduleName</code></td><td>Module name, the module name used in the pom.xml file Example: my-app</td></tr><tr><td><code>npf, noPropertiesFile</code></td><td>Do not generate Sealights property file</td></tr><tr><td><code>pfn, propertiesFileName</code></td><td>Path of Sealights property file to generate. Default is 'sealights.properties'</td></tr><tr><td><code>pathToMetaJson</code></td><td>Optional: Path to a json file with metadata regarding the build</td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr><tr><td><code>scmProvider</code></td><td>The provider name of your Source Control Management (SCM) tool. Values: Github, Bitbucket and Gitlab (Default is Github)</td></tr><tr><td><code>scmBaseUrl</code></td><td>The URL to the repository which contains the code. If not provided, the url of the remote GIT origin will be used</td></tr><tr><td><code>scmVersion</code></td><td>The version of your Source Control Management (SCM) tool. If not provided, cloud version is assumed</td></tr><tr><td><code>scm</code></td><td>Search for git information. Values: git, none (Default is git)</td></tr><tr><td><code>customFilterFile</code></td><td>Path to JSON format method filter rules file, format described <a href="https://sealights.atlassian.net/wiki/spaces/SUP/pages/1608646661/Ignoring+specific+methods+during+build+scan#Full-file-example">here</a></td></tr><tr><td><code>quiet</code></td><td>Suppresses console feedback messages only. Does not suppress log output when logging is configured to print to the console. The default value is <code>false</code>.</td></tr></tbody></table>

### Report build scan end <a href="#inlineextension-report-build-scan-end" id="inlineextension-report-build-scan-end"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-build-scanner.jar -buildend {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} {-failed | -ok}
```

{% endcode %}

<table><thead><tr><th width="261.19140625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>buildsessionid</code></td><td>Session ID of configuration created</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to file containing the Session ID of configuration created</td></tr><tr><td><code>ok</code></td><td>report the build scan was successful</td></tr><tr><td><code>failed</code></td><td>report the build scan was failed</td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr></tbody></table>

### Updating/Deleting a component from an integration build <a href="#inlineextension-updating-deleting-a-component-from-an-integration-build" id="inlineextension-updating-deleting-a-component-from-an-integration-build"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-build-scanner.jar {-componentUpdate | -componentDelete} {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} {-componentids <arg> | -componentfile <file>}
```

{% endcode %}

<table><thead><tr><th width="265.1328125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>buildsessionid</code></td><td>Session ID of configuration created for the integration build</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to file containing the Session ID of configuration created for the integration build</td></tr><tr><td><code>componentids</code></td><td>One or several build session ID's (comma separated) of the component(s) to be updated or deleted</td></tr><tr><td><code>componentfile</code></td><td>A path to a json file that is in the following format:<br><code>[{"appName":"","branch":"","build":""}, {...}]</code><br>or<br><code>[{"buildSessionId":"", {...}]</code></td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr></tbody></table>

## Test Listener <a href="#test-listener" id="test-listener"></a>

{% hint style="warning" %}
The `buildsessionid` and `buildsessionidfile` parameters are **deprecated** for test-runner commands. Use `labid` instead. These parameters remain supported only for unit-test runners that execute the build's code directly.
{% endhint %}

### Starting a test stage <a href="#inlineextension-starting-a-test-stage" id="inlineextension-starting-a-test-stage"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-test-listener.jar start {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} -testStage <arg> [-labid <arg>] [-proxy <arg>]
```

{% endcode %}

<table><thead><tr><th width="262.328125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>buildsessionid</code></td><td>Session ID of configuration created</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to file containing the Session ID of configuration created</td></tr><tr><td><code>testStage</code></td><td>Name of the test stage</td></tr><tr><td><code>labid</code></td><td>Unique ID for a set of test labs in case multiple labs are running simultaneously</td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr><tr><td><code>sl.calibrationLearning</code></td><td><p>(Optional) True/False. Passed as system property (e.g. <code>java -Dsl.calibrationLearning=true -jar sl-test-listener.jar start ...</code>) or via Env Var (<code>SL_CALIBRATION_LEARNING=true</code>)</p><p>If set to true, the test runner marks the test run as a calibration execution (for TIA). <em>Available from SeaLights agent v4.0.2610</em> <a data-mention href="/pages/WSIMrWVtmwrDw2bJ1rmj">/pages/WSIMrWVtmwrDw2bJ1rmj</a></p></td></tr></tbody></table>

### Upload report files <a href="#inlineextension-upload-report-files" id="inlineextension-upload-report-files"></a>

Report files must be junit style xml reports

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-test-listener.jar uploadReports {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} {-reportFile <arg>|-reportFilesFolder <arg>} -source <arg> -type <arg> [-labid <arg>] [-proxy <arg>]
```

{% endcode %}

<table><thead><tr><th width="263.57421875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>buildsessionid</code></td><td>Session ID of configuration created</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to file containing the Session ID of configuration created</td></tr><tr><td><code>reportFile</code></td><td>Path to report file (multiple entries can be provided)</td></tr><tr><td><code>reportFilesFolder</code></td><td>Path to folder containing report files (multiple entries can be provided). Note: all files in the folder will be uploaded</td></tr><tr><td><code>source</code></td><td>The reports provider. Example: <code>Junit xml report</code></td></tr><tr><td><code>type</code></td><td><p>Values:</p><ul><li><code>JUnitReport</code> - For uploading JUnit test report files</li><li><code>commitLog</code> - For uploading git style commit logs</li></ul></td></tr><tr><td><code>labid</code></td><td>Unique ID for a set of test labs in case multiple labs are running simultaneously</td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr></tbody></table>

### Ending a test stage <a href="#inlineextension-ending-a-test-stage" id="inlineextension-ending-a-test-stage"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -jar sl-test-listener.jar end {-token <arg> | -tokenfile <arg>} {-buildsessionid <arg> | -buildsessionidfile <arg>} [-labid <arg>] [-proxy <arg>]
```

{% endcode %}

<table><thead><tr><th width="277.390625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>tokenfile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>buildsessionid</code></td><td>Session ID of configuration created</td></tr><tr><td><code>buildsessionidfile</code></td><td>Path to file containing the Session ID of configuration created</td></tr><tr><td><code>labid</code></td><td>Unique ID for a set of test labs in case multiple labs are running simultaneously</td></tr><tr><td><code>proxy</code></td><td>Address of proxy to run connection through</td></tr></tbody></table>

## Installing test listener as Java Agent <a href="#installing-test-listener-as-java-agent" id="installing-test-listener-as-java-agent"></a>

The listener needs to be placed alongside the server and added to the JVM command line using the `-javaagent` parameter together with its required parameters.

Usually, the easiest is to place it in the `JAVA_OPTS="..."`, although it can also be placed in the JVM command itself.

{% code overflow="wrap" lineNumbers="true" %}

```sh
java -javaagent:/path/to/sl-test-listener.jar {-Dsl.token=<arg> | -Dsl.tokenFile=<arg>} {-Dsl.buildSessionId=<arg> | -Dsl.buildSessionIdFile=<arg>} [-Dsl.tags=<arg>] [-Dsl.labId=<arg>] [-Dsl.proxy=<arg>] [-Dsl.testStage=<arg>] [-Dsl.filesStorage=<folder>] [-Dsl.webappLocation=<arg>] -jar yourapp.jar
```

{% endcode %}

<table><thead><tr><th width="277.71484375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>javaagent</code></td><td>Path to Sealights Java test agent jar</td></tr><tr><td><code>sl.token</code></td><td>Access token generated from the SeaLights server</td></tr><tr><td><code>sl.tokenFile</code></td><td>Path to file containing the access token generated from the SeaLights server</td></tr><tr><td><code>sl.buildSessionId</code></td><td>Session ID of configuration created</td></tr><tr><td><code>sl.buildSessionIdFile</code></td><td>Path to file containing the Session ID of configuration created</td></tr><tr><td><code>sl.tags</code></td><td>One or several tags (comma separated) to be passed to Sealights in order to label the test listener in the cockpit</td></tr><tr><td><code>sl.labId</code></td><td>Unique ID for a set of test labs in case multiple labs are running simultaneously</td></tr><tr><td><code>sl.proxy</code></td><td>Address of proxy to run connection through</td></tr><tr><td><code>sl.testStage</code></td><td>Name of the test stage (When running with JMeter)</td></tr><tr><td><code>sl.filesStorage</code></td><td>Path to a folder that the agent can save temporary files to</td></tr><tr><td><code>sl.webappLocation</code></td><td>(Optional) Path to the folder containing the artifact of the application, by default 'webapps'.<br>If the property is provided, the agent looks recursively inside the <code>.war</code> and <code>.ear</code> files in the path defined by the property. The search stops on the first file found.<br>This parameter is used when the agent does not find automatically the <code>sltoken.txt</code> and <code>buildSessionId.txt</code> files added to the artifact by Sealights Maven or Gradle plugins during the build.</td></tr><tr><td><code>sl.collectorUrl</code></td><td>http/https dns to the collector for when working with lambda methods</td></tr></tbody></table>

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

In order to enable logs, you can set the following parameters as environment variables or, when using as `javaagent`, add them as `-Dsl.*` parameters.\
Both console output and file options are compatible and non-exclusive.

For logging into the console, add

{% code overflow="wrap" lineNumbers="true" %}

```sh
-Dsl.log.toConsole=true -Dsl.log.level=info [--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED]
```

{% endcode %}

For logging into a file, add

{% code overflow="wrap" lineNumbers="true" %}

```sh
-Dsl.log.toFile=true -Dsl.log.level=info -Dsl.log.folder=<path/with/permissions/> [--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED] [-Dsl.log.count=<value>] [-Dsl.log.limit=<arg>] [-Dsl.log.filename=<arg>]
```

{% endcode %}

<table><thead><tr><th width="291.0234375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>sl.log.level</code></td><td>Sets the log level to one of the following: "off", "error", "warn", "info", "debug"</td></tr><tr><td><code>sl.log.toConsole</code></td><td>Set to true to enable log output to the console</td></tr><tr><td><code>sl.log.toFile</code></td><td>Set to true to enable log output to a file</td></tr><tr><td><code>sl.log.folder</code></td><td>Provide a folder to save the log files in</td></tr><tr><td><code>sl.log.filename</code></td><td>Provide the name of the log file</td></tr><tr><td><code>sl.log.count</code></td><td>Limit the number of log files to create. Default: 10</td></tr><tr><td><code>sl.log.limit</code></td><td>Limit the size of the log file in megabytes (MB). Default value is 10 (i.e. 10*1024 KB)</td></tr><tr><td><code>--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED</code></td><td>Special JVM parameter to allow logging in Java 9 and later in addition to <code>-Dsl.log.*</code> options above.<br>If the option is not provided, the test listener will work as usual, but logging will not work.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/command-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.