Command-line syntax for Katalon Runtime Engine

Last updated: October 2026

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

note

To upgrade the default JRE 8 to higher versions, refer to this document for further details: Run tests with another JRE in the command line.

Requirements

• Katalon Runtime Engine is installed. See: Get started with Katalon Runtime Engine.
• A Katalon Runtime Engine License. To learn more about activating your license, you can refer to this document: Katalon license.

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.

-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 Katalon Runtime Engine:

• Firefox
• Chrome
• IE
• Edge
• Edge Chromium
• Safari
• Remote
• Android
• iOS
• Web Service

info

• If -testSuitePath is specified, -testSuiteCollectionPath is not required.
• Only Chrome, Firefox, and Remote are available for use in the Linux version.
• Web Service is used for Web Service test execution.
• To execute Web Service testing with Test Execution - Cloud, make sure to specify -browserType="Test Execution - Cloud" in your command. The -testcloudEnvironmentId should correspond to selecting Test Execution - Cloud Desktop browser > Linux > Chrome (any version).

-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 specified delay (in seconds).

retry=<number of retry times>
Number of times the test cases in the test suite are run.

retryStrategy=<allExecutions | failedExecutions | immediately>
Specifies which executions to retry (overrides the test suite setting):

• allExecutions: Retry all executions when the test suite fails.
• failedExecutions: Retry only the failed executions.
• immediately: Retry failed executions immediately (Enterprise only).

maxFailedTests=<T>

• Terminates execution when the number of failed tests reaches T.
• Counts failures in test cases, retried test cases, iterations, and retried iterations.

report.folderPath=<path>
Available from version 11.1.2. Destination folder for saving report files. Supports absolute or relative paths. Copies reports to the destination folder, preserving the full folder structure (including test suite collection and test suite name folders).

reportFolder=<path>
Deprecated from version 11.1.2. Use -report.folderPath instead. Still supported for backward compatibility but it is not recommended because it can generate reports with missing TSC/TS folder names.

reportFileName=<name>
Specifies the report file name (.html, .csv, .log). Default is report if not set.

Note: Only interpreted if report.folderPath / reportFolder is specified.

sendMail=<e-mail address>
Email address to receive the report files. If not specified, reports are not sent.

remoteWebDriverUrl=<remote web server url>
URL for the remote WebDriver server.

serverUrl=<server url>
URL for activating a Katalon Runtime Engine license. Required for Private Instance activation in console mode from v8.3.5 onwards.

appiumDirectory=<path>
Path to the Appium installation (e.g., /opt/homebrew/lib/node_modules/appium).

remoteWebDriverType=<Selenium | Appium>
Type of the remote WebDriver.

Note: Only interpreted if remoteWebDriverUrl is set.

deviceId=<Android device ID / iOS UUID>
Device ID for executing tests.

Note: Only interpreted if browserType is set.

executionProfile
Specifies the execution profile. From v7.6.0 onwards, applies to all test suites in a collection.

delayBetweenInstances=<value>

• Sets a delay between test suite executions in a collection.
• Value: Integer between 0 and 999 (seconds).
• Console log message shown when a suite is ready to start. See more details at Execute a Test Suite Collection.

g_<variable_name>
Override Execution Profile variables (e.g., g_userName="admin").

testSuiteQuery=<search-query>
Override dynamic test suite search queries from CLI.
Example: testSuiteQuery="ids=(Test Cases/TC1,Test Cases/TC2)"

testSuiteCollectionQuery
Enable/Disable test suites in a collection via index.

• testSuiteCollectionQuery="indexes=(0,3)" enables the 1st and 4th test suites.
• No index = all disabled.

maxResponseSize
Override project setting for max response size.

Example: maxResponseSize=400

--config -webui.autoUpdateDrivers=true
Allows WebDriver binaries to auto-update in console mode.

License retry mechanism (optional arguments)

These parameters allow you to control how Katalon Runtime Engine handles license retries when no license is available during test execution. Use them together to specify how often and for how long Katalon Runtime Engine should retry license activation.

-enableLicenseRetry
Enable or disable the license retry mechanism when no license is available.

• Default in version 9.x: false
• Default in version 10.x: false
• Default in version 11.x: false
• The input must be a Boolean

---

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

• Default value: 20
• Type: Integer

---

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

• Default value: 5
• Type: Integer
• Constraint: Must be ≥ 3
• Note: Should not exceed licenseRetryMaxDuration.

---

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

• Default value: 2
• Type: Integer
• Formula: licenseRetryMaxJitter / licenseRetryInterval
• Constraint: Should not exceed licenseRetryInterval.

---

How these parameters work together

When -enableLicenseRetry is set to true, Katalon Runtime Engine 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 Katalon Runtime Engine should retry, while -licenseRetryMaxJitter adds some randomness to avoid predictable retry intervals.

---

Example usage

Configure Katalon Runtime Engine 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 -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

notes

• You can exclude a list of hosts from proxy in the Manual proxy configuration. For more details, refer to: Proxy settings.
• You can pass proxy details via a request object in Web Service testing. For more details, refer to: 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

Use these arguments to configure proxy settings for Katalon Runtime Engine, especially in environments that require authentication.

---

proxy.auth.option Specifies how proxy settings should be handled.

• Options: NO_PROXY, USE_SYSTEM, MANUAL_CONFIG

-proxy.auth.server.type
Defines the type of proxy server.

• Options: HTTP, HTTPS, SOCKS

-proxy.auth.server.address Sets the address of the proxy server.

Example: localhost, katalon.com

-proxy.auth.server.port
Defines the port number used by the proxy server.

Example: 80, 8080, 9999

-proxy.auth.excludes
Specifies addresses that should bypass the proxy.

Example: 127.0.0.1, localhost, myserver.com

-proxy.auth.username
This option is required if the specified proxy server requires authentication.

Example: MyProxyUsername

-proxy.auth.password
This option is required if the specified proxy server requires authentication.

Example: MyProxyPassword

System proxy arguments

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

-proxy.system.server.type
Available types: HTTP, HTTPS, or SOCKS.

-proxy.system.server.address
Example: localhost, 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 your proxy requires authentication.

-proxy.system.applyToDesiredCapabilities
Example: true or false.

---

For versions below 7.5.0

-proxy.option
Available values: NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.server.type
Available types: HTTP, HTTPS, or SOCKS.

-proxy.server.address
Example: localhost, 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

Katalon True integration arguments

-testOpsProjectId
The ID of the Katalon True 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 True.

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: Visual Testing Overview

Example: -testOps.baselineCollectionId=1234

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

• Public Cloud
• Private Instance
• Staging and Production

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

-testOps.customField=<key1:value1, key2:value2>
Assign values to existing custom fields on the test run using their keys. Multiple key-value pairs can be specified, separated by a comma. Create the custom fields in Katalon True first and configure them to apply to Test Run objects. See Customizable Fields.

-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 assigns it to the test run if the tag was never created before.

-testOps.enabled=true/false
From version 10.1.0 onwards, you can enable or disable Katalon True integration from the command line.
This option overrides the settings in Project Settings.

-testOps.testRunName=<name> From version 10.3.1 onwards, you can adjust the name of the test run uploaded to Katalon True.

If not specified or thetestRunName value has an invalid format, the original name of the executed TS and TSC will be used.

Test Execution - Cloud 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).

important

• To get the Test Execution - Cloud 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="Cloud Execution", these parameters set the execution environment to mobile browser on Cloud Execution. 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 API Key (Available in 7.8 and later).

-kobitonDeviceId=<yourKobitonDeviceId>
ID of the destination where the result is uploaded on it.

Azure DevOps integration arguments

-adoPlanId=<testplanID1,testplanID2>
IDs of the test plan used for submitting test run(s). Supports multiple values separated by comma.

-adoTestRunName=<testRunName>
Create test run(s) on ADO with the specified name.

--info -adoDefinitionID=<definitionID>
Get the latest completed Build ID of the specified Definition ID and pass it to Test Run properties on ADO.

---

AI execution arguments

The following arguments configure AI for local Katalon Runtime Engine executions. They can override project-level AI settings; your account admin's AI settings still apply when Katalon Runtime Engine is activated online.

-ai.provider=<ai_provider>
Value of the supported the AI provider, including: katalon_ai, openai, azure_openai, gemini, openai_compatible, aws_bedrock.
Based on the selected AI provider, you may need to specify additional required or optional arguments.

tip

If you have already configured an AI key in Katalon AI Assistant, the Command Builder automatically generates the required command-line arguments for you.
This applies to the Katalon AI key, the Organization key, and Personal AI keys.

Katalon AI key and organization key

To use the AI key your account admin manages, activate Katalon Runtime Engine online and specify -ai.provider=katalon_ai. No additional AI provider arguments are required. Katalon Runtime Engine uses the Katalon AI key or your organization's key, whichever your admin set on True Platform. For details, see Configure AI services.

Your admin manages the model and token limit of these keys, so -ai.model and -ai.maxCompletionToken do not apply to them.

How your admin's AI settings apply

Requirements

• Katalon Runtime Engine version 11.7.0 onwards.

When Katalon Runtime Engine is activated online with -apiKey, your account admin's AI settings decide which key and features are available. Project settings and command-line overrides then determine which available features run:

Your admin allows	-ai.provider=katalon_ai	-ai.provider=<personal provider>	Available AI features
The admin's key and personal keys	The admin's key	Your personal key	The ones your admin left on
The admin's key only	The admin's key	The admin's key. Your personal key is not used.	The ones your admin left on
Personal keys only	No AI	Your personal key	The ones your admin left on
AI turned off	No AI	No AI	None

With an offline license, admin settings do not apply. Use a personal key; the Katalon AI key and organization key require online activation. Project settings and command-line overrides still determine which features run.

When AI is not available for a run, AI self-healing is skipped with the reason in the log, and LLM keywords fail the step with the reason. For the messages, see When AI is unavailable.

Personal AI keys

In this mode, all required provider arguments must be specified via command line.

OpenAI

• -ai.provider=openai
• -ai.apiKey
• -ai.orgID (optional)
• -ai.model (optional)
• -ai.maxCompletionToken (optional)

Azure OpenAI

• -ai.provider=azure_openai
• -ai.apiKey
• -ai.apiVersion
• -ai.baseUrl
• -ai.deploymentName
• -ai.maxCompletionToken (optional)

Gemini

• -ai.provider=gemini
• -ai.apiKey
• -ai.baseUrl
• -ai.model (optional)
• -ai.maxCompletionToken (optional)

OpenAI-compatible

• -ai.provider=openai_compatible
• -ai.baseUrl: The API endpoint for your OpenAI-compatible service.
• -ai.apiKey (optional)
• -ai.apiKeyHeaderName (optional)
• -ai.model (optional)
• -ai.maxCompletionToken (optional)

AWS Bedrock

• -ai.provider=aws_bedrock
• -ai.awsAccessKey: Your AWS access key ID.
• -ai.awsSecretKey: The secret key paired with your access key ID for authentication.
• -ai.awsRegion: The AWS region where your Bedrock model is available.
• -ai.model
• -ai.maxCompletionToken (optional)

AI capabilities switch in Katalon Runtime Engine

From Katalon Studio 11.7.0, each project has an Enable AI capabilities for this project switch. See Turn AI capabilities on or off for a project. In Katalon Runtime Engine executions:

• When the switch is off in the project and no command-line override is provided, no AI failure analysis or AI self-healing runs.
• An AI failure analysis or AI self-healing argument (true or false) overrides the switch and the project setting for that feature only, subject to your admin's AI settings. For example, -ai.enablePdfReportAnalysis=true turns on PDF analysis when the project switch is off and your admin allows the feature.
• There is no argument for the switch itself.

Turn AI failure analysis on or off

By default, a Katalon Runtime Engine execution follows the project settings in Project > Settings > AI Capabilities. Use the following arguments to override them for one execution. Each argument affects only its own output.

-ai.enableHtmlReportAnalysis=<boolean>
Turn AI failure analysis on (true) or off (false) for the HTML report.

-ai.enablePdfReportAnalysis=<boolean>
Turn AI failure analysis on (true) or off (false) for the PDF report. Available from Katalon Studio 11.7.0.

-ai.enableEmailReportAnalysis=<boolean>
Turn AI failure analysis on (true) or off (false) for the email report.

note

• From 11.7.0, -ai.enableHtmlReportAnalysis affects the HTML report only. In earlier versions it also turned on the analysis for the PDF report. To turn on the PDF analysis, add -ai.enablePdfReportAnalysis=true.
• If the project has no saved PDF setting, the PDF report follows the HTML setting saved in the project, not -ai.enableHtmlReportAnalysis.
• A value other than true or false is ignored, and the project setting applies.

Add these arguments to a Katalon Runtime Engine execution command to analyze failures in PDF and email reports, but not in the HTML report:

-ai.provider="katalon_ai"
-ai.enableHtmlReportAnalysis=false
-ai.enablePdfReportAnalysis=true
-ai.enableEmailReportAnalysis=true

AI self-healing

Use the following arguments to enable AI self-healing in Katalon Runtime Engine executions. Each argument overrides the project's AI self-healing setting and the AI capabilities switch, for its own platform only. See AI capabilities switch in Katalon Runtime Engine.

For Web

• -execution.selfheal.web.ai.enabled=<boolean>
  Enable or disable AI self-healing for Web UI.

• -execution.selfheal.web.ai.inputSources="[<source>]"
  Specify data sources for Web AI analysis. Supports multiple values separated by comma.

Supported values (formatted):

• \"PAGE_SOURCE\"
• \"ACCESSIBILITY_TREE\"
• \"FULL_PAGE_SCREENSHOT\"
• \"ELEMENT_SCREENSHOT\"

Note: Use escaped double quotes only for inline command-line commands. In console.properties, use plain key-value syntax, for example: execution.selfheal.web.ai.inputSources=["PAGE_SOURCE","ACCESSIBILITY_TREE"]. See Use the console.properties file for more details.

Example:

-ai.provider="openai"
-ai.model="gpt-4o-mini"
-ai.apiKey="sk-proj-..."
-execution.selfheal.web.ai.enabled="true"
-execution.selfheal.web.ai.inputSources="[\"PAGE_SOURCE\",\"ACCESSIBILITY_TREE\"]"

For Mobile

-execution.selfheal.mobile.ai.enabled=<boolean>
Enable or disable AI self-healing for Mobile.

-execution.selfheal.mobile.ai.inputSources="[<source>]"
Specify data sources for Mobile AI analysis. Supports multiple values separated by comma.

Supported values (formatted):

• \"PAGE_SOURCE\"
• \"FULL_PAGE_SCREENSHOT\"
• \"ELEMENT_SCREENSHOT\" Note: Use escaped double quotes only for inline command-line commands. In console.properties, use plain key-value syntax, for example: execution.selfheal.mobile.ai.inputSources=["PAGE_SOURCE","ELEMENT_SCREENSHOT","FULL_PAGE_SCREENSHOT"]. See Use the console.properties file for more details.

Example:

-ai.provider="katalon_ai"
-execution.selfheal.mobile.ai.enabled=true
-execution.selfheal.mobile.ai.inputSources="[\"PAGE_SOURCE\",\"ELEMENT_SCREENSHOT\"]"

Deprecated AI execution syntax

The legacy -studioAssist.* syntax is deprecated since 11.1.0. You can still use it for backward compatibility.

The legacy names of the AI failure analysis arguments work the same as the current ones:

• -studioAssist.enableHtmlReportAnalysis: same as -ai.enableHtmlReportAnalysis.
• -studioAssist.enableEmailReportAnalysis: same as -ai.enableEmailReportAnalysis.

Katalon AI key and organization key

With online activation, -studioAssist.provider=katalon_ai uses the Katalon AI key or your organization's key, whichever your admin set on True Platform. Your admin manages the model and token limit, so -studioAssist.model and -studioAssist.maxCompletionToken do not apply.

Personal AI keys

In this mode, all required provider arguments must be specified via command line.

OpenAI

• -studioAssist.provider=openai
• -studioAssist.apiKey
• -studioAssist.orgID (optional)
• -studioAssist.model (optional)
• -studioAssist.maxCompletionToken (optional)

Azure OpenAI

• -studioAssist.provider=azure_openai
• -studioAssist.apiKey
• -studioAssist.apiVersion
• -studioAssist.baseUrl
• -studioAssist.deploymentName
• -studioAssist.maxCompletionToken (optional)

Gemini

• -studioAssist.provider=gemini
• -studioAssist.apiKey
• -studioAssist.baseUrl
• -studioAssist.model (optional)
• -studioAssist.maxCompletionToken (optional)

OpenAI-compatible

• -studioAssist.provider=openai_compatible
• -studioAssist.baseUrl: The API endpoint for your OpenAI-compatible service.
• -studioAssist.apiKey (optional)
• -studioAssist.apiKeyHeaderName (optional)
• -studioAssist.model (optional)
• -studioAssist.maxCompletionToken (optional)

AWS Bedrock

• -studioAssist.provider=aws_bedrock
• -studioAssist.awsAccessKey: Your AWS access key ID.
• -studioAssist.awsSecretKey: The secret key paired with your access key ID for authentication.
• -studioAssist.awsRegion: The AWS region where your Bedrock model is available.
• -studioAssist.model
• -studioAssist.maxCompletionToken (optional)