# Command Reference

## Integrating into the build.gradle files <a href="#integrating-into-the-build.gradle-files" id="integrating-into-the-build.gradle-files"></a>

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

```
java -jar sl-build-scanner.jar -gradle -configfile <arg> -workspacepath <arg> [-pluginversion <arg>] [-repoConfig <arg>] [-includedProjects <arg>] [-excludedProjects <arg>]
```

{% endcode %}

<table><thead><tr><th width="166.83203125">Parameter</th><th>description</th></tr></thead><tbody><tr><td>configfile</td><td>The path to the JSON configuration you created with the parameters to be provided to the SeaLights Gradle Plugin</td></tr><tr><td>workspacepath</td><td>The base path to the location of the build.gradle files to update</td></tr><tr><td>pluginversion</td><td>(<em>Optional</em>) Version of the Gradle SeaLights Plugin to insert into the build.gradle.<br><em>This command line option overrides the configuration from the JSON file.</em></td></tr><tr><td>repoConfig</td><td><em>(Optional)</em> Configuration of repositories from which the SeaLights Gradle plugin will be taken.<br><br>This will be put as is in a Gradle script's buildScript { repositories { /* repoConfig */ } } block.<br>For multiline config, separate the lines by semicolon ;, e.g. -repocConfig "mavenLocal(); mavenCentral()"</td></tr><tr><td>includedProjects</td><td><em>(Optional)</em> Comma-separated list of Gradle (sub)projects to include in SeaLights integration.<br>When not set or empty, all (sub)projects are included.<br><em>This command line option overrides the configuration from the JSON file.</em></td></tr><tr><td>excludedProjects</td><td><em>(Optional)</em> Comma-separated list of Gradle (sub)projects to exclude from SeaLights integration.<br>If a project’s name is on both includedProjects and excludedProjects, this option supersedes and overrides includedProjects.<br><em>This command line option overrides the configuration from the JSON file.</em></td></tr></tbody></table>

## Restoring the build.gradle file to its previous state <a href="#restoring-the-build.gradle-file-to-its-previous-state" id="restoring-the-build.gradle-file-to-its-previous-state"></a>

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

```
java -jar sl-build-scanner.jar -restoreGradle -workspacepath <arg>
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="163.7734375">Flag</th><th>Use</th></tr></thead><tbody><tr><td>workspacepath</td><td>The base path to the location of the build.gradle files to update</td></tr></tbody></table>

## JSON Configuration file parameters <a href="#json-configuration-file-parameters" id="json-configuration-file-parameters"></a>

Create a JSON configuration file with the following parameters in order to provide the necessary configuration fields to the SeaLights Gradle plugin:

1. **token** or **tokenFile** - set with a token or a file containing the token obtained from the SeaLights dashboard
2. If you create a Build Session ID externally, provide the following fields:
   1. **buildSessionId** or **buildSessionIdFile** - Set with a build session id or a file containing the build session id created by the config step
   2. **createBuildSessionId** - Set to **false**
3. If you want to create a Build Session ID using the SeaLights Gradle plugin, provide the following fields:
   1. **createBuildSessionId** - Set to **true**
   2. **appName** - Name of the application as you want to see it on the SeaLights dashboard
   3. **branchName** - Name of the branch as you want to see it on the SeaLights dashboard
   4. **buildName** - Name of the build as you want to see it on the SeaLights dashboard
   5. **packagesIncluded** - Comma-separated list of packages to include in scan. Note: This is defining a subset, so it must include the astrix to include all sub packages/classes
   6. **packagesExcluded** - (Optional) Comma-separated list of packages to include in scan.  Note: This is defining a subset, so it must include the astrix to include all sub packages/classes
4. **executionType** - Provide which executions need to handled by the Gradle plugin
   1. **full** - Execute both the build scanner and the test listener. This will appear as `runTestOnly=false` in the integrated gradle file.
   2. **testsonly** - Execute only the test listener. This will appear as `runTestOnly=true` in the integrated gradle file.
   3. **scanonly** - Execute only the build scanner
5. **filesincluded** - (Optional) Set to the binary files to scan. Default: \*.class
6. **filesexcluded** - (Optional) Set to the binary files to excluded from the scan. Default: \*test-classes\*
7. **workspacepath** - Set to the path to the binary files to scan. Default: project.buildDir
8. **recursive** - (Optional) Set to true to scan all the subdirectories of workspacepath. Default: true
9. **includeResources** - (Optional) Set to include the token and build session ID files in the built resources
10. **includeTokenResource** - (Optional) On top of `includeResources` above, set to `false` to exclude the token file from the built resources. By default is `true`.
11. **testTasksAndStages** - (Optional) Mapping of test tasks’s names to test stage names as they will be displayed on the SeaLights dashboard. It should be of the format {"testTask1":"testStage1", "testTask2":"testStage2"}
12. **labId** - (Optional) Unique ID for a set of test labs in case multiple labs are running simultaneously
13. **filesStorage** - Set to the temp folder for the agent to create temporary files in. For example **/tmp**
14. **logEnabled** - Set to **true** if you want a log to be created
15. **logLevel** - Set the log level to create. For example **INFO**
16. **logToFile** - Set to true if you want the log to written to a file
17. **logToConsole** - Set to true if you want the log to written to the console
18. **proxy** - (Optional) Address of proxy to run connection through
19. **sealightsJvmParams** - Containing and array of all the JVM parameters you want to pass to all the SeaLights execution steps (build\&test).\
    Note: the key and values must always be strings. It should be of the format {"key1":"val1", "key2":"val2"}
20. **buildScannerParams -** Containing a map of all the parameters you want to pass to all the SeaLights build execution step only. Note: the key and values must always be strings
21. **testListenerJvmParams -** Containing a map of all the parameters you want to pass to all the SeaLights test execution step only, Note: the key and values must always be strings
22. **pluginVersion** - (Optional) version of the SeaLights Gradle plugin. Default: latest.release
23. **gradleProjectConfig** - (Optional) JSON elment with definitions of following Gradle project’s integration properties:
    1. **includedProjects** - (Optional) array of names of (sub)projects to include in integration.\
       Projects from outside this array will not be built with SeaLights integration. E.g. \["subProject1", "subProject3"]. Default: all projects included.
    2. **excludedProjects** - (Optional) array of names of (sub)projects to exclude in integration.\
       Projects from this array will not be built with SeaLights integration. E.g. \["subProject1", "subProject3"]. Default: \[]
    3. **repoConfig** - (Optional) The configuration of repositories from which the SeaLights Gradle plugin will be taken. This will be put as is in a Gradle script's buildScript { repositories { /\* repoConfig \*/ } } block.\
       For multi-line configuration, use the \n character in JSON string. Default: mavenCentral()
    4. **useOnlyProjectRepoSection -** (Optional) Flag to skip injecting `repositories` section to result `build.gradle` file to allow use only customer-defined list of repositories.
24. **metadata** section with CI details
    1. **jobName** - Set to the name of the build job. For example **${JOB\_NAME}**
    2. **logsUrl** - Set to the link that the SeaLights dashboard should provide to view the build log. For example **${BUILD\_URL}/console**

## Additional Configuration Options <a href="#additional-configuration-options" id="additional-configuration-options"></a>

### Tagging <a href="#tagging" id="tagging"></a>

You can add tags to be viewed in the Sealights Cockpit for the agents started by this Gradle job by passing them through the sl.tags property in the **sealightsJvmParams** field

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

```javascript
"sealightsJvmParams": {
    "sl.tags": "mytag",
}
```

{% endcode %}

### Support for Special Use Cases - Test Runners  <a href="#support-for-special-use-cases-test-runners" id="support-for-special-use-cases-test-runners"></a>

Additional parameters exist to support special use cases when using the SeaLights Gradle Plugin with your Test Runner. You can learn about those: [test-runners-and-java-agent-special-cases](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/advanced-features/test-runners-and-java-agent-special-cases "mention")