Skip to main content

Command-line syntax in Katalon Runtime Engine

This guide lists out the supported command-line syntax and arguments of Katalon Runtime Engine.

Note:

Requirements​

Use plugins in console mode​

You can also continue using your plugins of choice with console commands. See this guide: Use Plugins in Console Mode.

General arguments​

Here's the list of options supported for the katalonc commands for Katalon Studio.

Required arguments​

-runMode=console

Enable console mode.

-projectPath=<path>

Specify the project location (include .prj file). The absolute path must be used in this case.

-testSuitePath=<path>

Specify the test suite file (without extension .ts). The relative path (root being project folder) must be used in this case.

-testSuiteCollectionPath=<path>

Specify the test suite file (without extension .tsc). The relative path (root being project folder) must be used in this case.

Note:

  • If -testSuitePath is specified, -testSuiteCollectionPath is not required.

-browserType=<browser>

Specify the browser type used for Test Suite execution or Test Suite Collection execution (the specified browser is used for all test suites in that collection).

The following browsers are supported in KRE:
  • Firefox
  • Chrome
  • IE
  • Edge
  • Edge (Chromium)
  • Safari
  • Remote
  • Android
  • iOS
  • Web Service
Note:

  • Only Chrome, Firefox, and Remote are available for use in the Linux version.

    Web Service is used for Web Service test execution.

-apiKey=<Your_API_Key> or -apikey=<Your_API_Key>
API Keys are used to represent a user's credentials. See: API Keys.

Optional arguments​

-statusDelay=<seconds>

System updates execution status of the test suite after the delay period (in seconds) specified.

-retry=<number of retry times>

Number of times running test cases in the test suite.

-retryStrategy=<allExecutions | failedExecutions | immediately>
This option is supported in version 7.6 onwards. Specify which execution to be retried (this parameter overrides setting in test suite file):
  • allExecutions: Retry all executions when the Test Suite fails
  • failedExecutions: Retry only failed executions when the Test Suite fails
  • immediately: Retry a failed execution of a test case or test data immediately. (Only for Katalon Studio Enterprise users)
-maxFailedTests=<T>
  • From version 8.1.0, you can terminate a test suite/ test suite collection execution based on the number of test failures.
  • Set <T> as the maximum number of total test failures allowed in the execution. Reaching <T> terminates the test execution.
  • A test failure is counted when any of these type of tests fails: test case, retried test case, test iteration, or retried test iteration.
-reportFolder=<path>

Specify the destination folder for saving report files. You can use an absolute path or relative path (root being project folder).

-reportFileName=<name>

Specify the name for report files (.html, .csv, .log). If not provided, the system uses the name "report" (report.html, report.csv, report.log).

Note:

  • -reportFileName is only interpreted if -reportFolder is specified.

-sendMail=<e-mail address>
Specify the e-mail address for receiving report files. If the e-mail address was not specified, the report files are not to be sent.
-remoteWebDriverUrl=<remote web server url>

Specify the remote web driver URL.

-serverUrl=<server url>

Specify the server URL that you use to activate a KRE license. From Katalon Studio version 8.3.5 onwards, you can use this parameter to activate a KRE license with Private Instance while executing in console mode. For example: -serverUrl="https://admin-tenant1.katalon-cloudops.com".

-appiumDirectory=<path>

The directory where Apppium is installed. For example, the path can be "/opt/homebrew/lib/node_modules/appium".

-remoteWebDriverType=<Selenium | Appium>

Remote web's driver type.

Note:

  • remoteWebDriverType is only interpreted if remoteWebDriverUrl is specified.

-deviceId=<device Id for Android/device UUID for ios>

Specify the device's ID to execute test scripts using this device.

Note:
  • -deviceId is only interpreted if -browserType is specified.
-executionProfile

Specify the execution profile that a test suite executes with

From version 7.6.0 onwards, you can use this option in Test Suite Collection execution. The specified execution profile is applied to all test suites in that collection.

-delayBetweenInstances=<value>
  • From Katalon version 8.2.0 onwards, you can set a delay between each test suite execution in a Test Suite Collection.
  • Value is a positive integer from 0-999 seconds.
  • When a test suite is ready to start, KRE prints a message in Console Log: Test suite ${testSuiteID} is ready to start at ${currentTimeStamp}
-g_<variable_name>

Override Execution Profile variables.

Example: -g_userName="admin"

-testSuiteQuery=<search-query>

From version 7.8.0, you can override the search query of the dynamic test suite from the CLI.

<search-query> is the search condition that follows the query syntax of the installed query provider plugin. For detailed instruction, follow this guide: Pass the search query to the CLI for dynamic test suite execution.

Example: -testSuiteQuery="ids=(Test Cases/TC1_Verify Successful Login,Test Cases/TC2_Verify Successful Appointment)"

-testSuiteCollectionQuery

From version 8.0.0, you can enable or disable Test Suite(s) in a Test Suite Collection using their index values.

  • The Run column in the Test Suite Collection contains checkboxes for each Test Suite. Checked means enabled to run.

  • The -testSuiteCollectionQuery parameter lets you enable specific Test Suites by specifying their index positions (starting from 0).

    Example: -testSuiteCollectionQuery="indexes=(0,3)"

    This runs the first (index 0) and fourth (index 3) Test Suites.

  • If you don't input any indexes, all Test Suites will be disabled (similar to unchecking the checkboxes in the UI).

-maxResponseSize

Override the maximum response size in project setting (available from version 7.6). Learn more about Web Service Settings.

Example: -maxResponseSize=400

-licenseRelease -orgID=<organization's id>

From version 8.0.0, you can release the previous execution session before checking the license.

Example:

-licenseRelease=true

-orgID=89151

--config -webui.autoUpdateDrivers=true
Allow WebDriver binaries to be updated automatically in console mode.

License retry mechanism (optional arguments)​

These parameters allow you to control how KRE handles license retries when no license is available during test execution. Use them together to specify how often and for how long KRE should retry license activation.
-enableLicenseRetry
Enable or disable the license retry mechanism when no license is available.

  • Default value in version 9.x: false

  • Default value in version 10.x: true

  • The input must be a valid boolean.

-licenseRetryMaxDuration
Specify the maximum duration (in minutes) that KRE will retry license activation. After this time, KRE will stop retrying if activation is not successful.

  • Default value: 20 minutes.

  • The input must be a valid integer.

-licenseRetryInterval
Specify how often (in minutes) KRE should retry the license activation attempt.

  • Default value: 5 minutes.

  • The input must be a valid integer.

  • This value should not exceed the licenseRetryMaxDuration.

-licenseRetryMaxJitter
Specify the jitter factor (in minutes) to add randomness to the retry interval.

  • Default value: 2 minutes.

  • The input must be a valid integer.

  • The jitter factor is calculated as licenseRetryMaxJitter / licenseRetryInterval.

  • This value should not exceed the licenseRetryInterval.

How these parameters work together:

  • When -enableLicenseRetry is set to true, KRE will attempt to reactivate the license whenever it encounters an issue where no license is available.

  • You can control how long the retry process will last using -licenseRetryMaxDuration.

  • The -licenseRetryInterval specifies how frequently KRE should retry, while the -licenseRetryMaxJitter adds some randomness to avoid predictable retry intervals.

Example usage:

To configure KRE to retry license activation for up to 10 minutes, with retry attempts every 3 minutes and a jitter factor of 1 minute:

katalon.exe -noSplash -runMode=console -retry=2 -retryStrategy=failedExecutions -statusDelay=60 -projectPath="%projectPath%" -testSuitePath=%testSuite% -browserType="Firefox" -executionProfile="default" -apiKey="<your_api_key>" -orgID=<your_org_id> -testOpsProjectId=<your_project_id> --config -webui.autoUpdateDrivers=true -licenseRelease=true -reportFolder=./Reports/Your_Report_Folder -enableLicenseRetry=true -licenseRetryMaxDuration=10 -licenseRetryInterval=3 -licenseRetryMaxJitter=1

Windows-specific arguments​

-consoleLog

Display log in the console. Only use this option when running Katalon Studio in Windows Command Prompt. Do not use this option in other OSes or CI tools, for example Jenkins.

-noExit

Keep the console open after the execution is completed. Only use this option when running Katalon Studio in Windows Command Prompt. Do not use this option in other OSes or CI tools, for example Jenkins.

Proxy arguments​

Note:

  • From version 7.5.0 onwards, there are two types of proxy configurations: authentication and system proxies. To learn more about configuring different proxy preferences, you can refer to this document: Proxy Preferences for further details.

  • From version 7.2.0 onwards, you can exclude a list of hosts from proxy in the Manual proxy configuration. To learn more about manually excluding domains from proxy, you can refer to this document: Proxy settings.

  • From version 7.0.0 onwards, you can pass proxy details via a request object in Web Service testing. To learn more about passing proxy details in script mode, you can refer to this document: Override proxy details in the test script.

These proxy options must be used with --config parameter, for example: --config -proxy.auth.option=MANUAL_CONFIG 

katalonc -noSplash -runMode=console -projectPath="C:\Users\Katalon Studio\Project\YourProject.prj" -retry=0 -testSuitePath="Test Suites/download" -executionProfile="default" -browserType="Chrome" --config -proxy.auth.option=MANUAL_CONFIG -proxy.auth.server.type=HTTP -proxy.auth.server.address=192.168.1.16 -proxy.auth.server.port=16000 -proxy.system.option=MANUAL_CONFIG -proxy.system.server.type=HTTP -proxy.system.server.address=127.0.0.1 -proxy.system.server.port=12701 -proxy.system.username=katalon -proxy.system.password=T3stP@zZW0rol -proxy.system.applyToDesiredCapabilities=true

Authentication proxy arguments​

-proxy.auth.option

The available values for this option are: NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.auth.server.type

The available server types are: HTTP, HTTPS, or SOCKS.

-proxy.auth.server.address

Example: localhost, katalon.com.

-proxy.auth.server.port

Example: 80, 8080, 9999.

-proxy.auth.excludes

Exclude the specified server.

For example: 127.0.0.1, localhost, myserver.com.

-proxy.auth.username
Example: MyProxyUsername. This option is required if the specified proxy server requires authentication.
-proxy.auth.password

Example: MyProxyPassword. This option is required if the specified proxy server requires authentication.

System proxy arguments​

For versions 7.5.0 onwards
-proxy.system.option

The available values for this options are: NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.system.server.type

HTTP, HTTPS, or SOCKS

-proxy.system.server.address

Example: locahost, katalon.com.

-proxy.system.server.port

Example: 80, 8080, 9999.

-proxy.system.excludes

Example: 127.0.0.1, localhost, myserver.com.

-proxy.system.username

Example: MyProxyUsername. This option must be specified if your proxy requires authentication.

-proxy.system.password

Example: MyProxyPassword. This option must be specified if you proxy requires authentication.

-proxy.system.applyToDesiredCapabilities

Example: true or false.

For versions below 7.5.0
-proxy.option

NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.server.type

HTTP, HTTPS, or SOCKS.

-proxy.server.address

Example: locahost, katalon.com.

-proxy.server.port

Example: 80, 8080, 9999.

-proxy.excludes

Example: 127.0.0.1, localhost, myserver.com.

-proxy.username

Example: MyProxyUsername. This option must be specified if your proxy requires authentication.

-proxy.password

Example: MyProxyPassword. This option must be specified if your proxy requires authentication.

Integration arguments​

TestOps integration arguments​

-testOpsProjectId

The ID of the TestOps Project that is associated with the test run.

Example -testOpsProjectId=123456.

-testOpsReleaseId
The ID of the TestOps release that is associated with the test run.
--info -buildLabel=<text> -buildURL=<text>

Pass the build's label and URL, which are displayed in Katalon TestOps.

Example:
--info -buildLabel="Build 1" -buildURL="http://192.168.35.52:8080/job/katalon-demo/job/master/179/"
-testOpsBuildId

From version 8.0.0, you can specify the build ID to update the Test Suite/Test Suite Collection report.

Example:-testOpsBuildId=24

-testOps.baselineCollectionId=<CollectionId>

From version 8.4.0 onwards, you can specify a baseline collection ID to which Katalon visual testing functionality compares newly captured images in your test runs. See: Use TestOps Visual Testing.

For example: 
-testOps.baselineCollectionId=1234
-testOps.serverUrl=<URL>
From version 8.4.0 onwards, you can specify the URL for TestOps server for authentication and integration. You can use this argument to work with different offerings of TestOps, including:
Note:

  • If -testOps.serverUrl is not specified, the default URL is https://testops.katalon.io.

-testOps.customField=<key1:value1, key2:value2>
Assigns pre-existent custom fields to the test run. Multiple custom fields can be assigned, separated by a comma. The command also creates a custom field and assign it to the test run if the custom field was never created before. To understand more about custom field, see Custom Fields and Tags.
-testOps.tag=<tag1, tag2>
Assign pre-existent tags to the test run. Multiple tags can be assigned, separated by a comma. The command also creates a tag and assign it to the test run if the tag was never created before. To understand more about tag, see Custom Fields and Tags.

TestCloud integration arguments​

-testcloudEnvironmentId=<ID>
The ID of the environment which corresponds to a combination of OS, browser type and browser version to execute (Available from 8.2.5 onwards).
Note:

  • To get the TestCloud environment ID, open Katalon Studio and use the command builder. For detailed information, follow this guide: Generate Command with Command Builder.

  • This parameter already contains the information about browser type. Therefore, the -browserType parameter is not generated in this integration.

-testcloudTunnel
Allow the execution to be performed via a tunnel (Available from 8.2.5 onwards).
--testcloudMobileDeviceId=<device name> and -testcloudMobileId=<device name>
When combined with -browserType="TestCloud", these parameters set the execution environment to mobile browser on TestCloud. To generate the correct device name values, you should use Command Builder in Katalon Studio. See: Run tests on mobile browsers in Katalon Runtime Engine.

Kobiton integration arguments​

--config -kobiton.authentication.username=<yourKobitonUsername> -kobiton.authentication.password=<yourPassword>

Passing Kobiton username and password.

--config -kobiton.authentication.serverUrl=<defaultKobitonServer> -kobiton.authentication.username=<yourKobitonUsername> -kobiton.authentication.apiKey=<yourKobitonAPIKey>

Passing Kobiton Server URL, username, and APIKey (Available in 7.8 and later).

-kobitonDeviceId=<yourKobitonDeviceId>

ID of the destination where the result is uploaded on it.

Azure DevOps integration arguments​

-adoPlanId=<testplanID>

ID of the test plan used for submitting test run(s)(available from version 8.0.0).

-adoTestRunName=<testRunName>

From version 8.0.0, you can create test run(s) on ADO with the specified name.

--info -adoDefinitionID=<definitionID>

From version 8.0.0, you can get the latest completed Build ID of the specified Definition ID and pass it to Test Run properties on ADO.

Was this page helpful?