# 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="advanced-features/test-runners-and-java-agent-special-cases">test-runners-and-java-agent-special-cases</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>