Skip to content
Command line client for invoking utPLSQL
Java Shell PLSQL
Branch: develop
Clone or download

latest-release license build


Java command-line client for utPLSQL v3.

Provides an easy way of invoking utPLSQL from command-line. Main features:

  • Ability to run tests with multiple reporters simultaneously.
  • Ability to save output from every individual reporter to a separate output file.
  • Allows execution of selected suites, subset of suite.
  • Maps project and test files to database objects for reporting purposes. (Comming Soon)


Published releases are available for download on the utPLSQL-cli GitHub Releases Page.

You can also download all development versions from Bintray.


  • Java SE Runtime Environment 8
  • When using reporters for Sonar or Coveralls client needs to be invoked from project's root directory.
  • Due to Oracle license we can't ship the necessary oracle libraries directly with utPLSQL-cli. Please download the libraries directly from oracle website and put the jars into the "lib" folder of your utPLSQL-cli installation
    • Oracle ojdbc8 driver
    • It is highly recommended that you also use the orai18n library, especially if you use a charset different than UTF-16 or are on Oracle 11g.
    • All of the above can be downloaded from Oracle download site


The latest CLI is always compatible with all database frameworks of the same major version. For example CLI-3.1.0 is compatible with database framework 3.0.0-3.1.* but not with database framework 2.x.

Localization and NLS settings

utPLSQL-cli will use the environment variables "LC_ALL" or "LANG" to change the locale and therefore the client NLS settings. If neither environment variable is available, it will use the JVM default locale.

Example: to change the NLS-settings to English American, you can do the following:

export LC_ALL=en_US.utf-8

The charset-part of LC_ALL is ignored.

In addition, utPLSQL-cli will use an existing "NLS_LANG" environment variable to create corresponding ALTER SESSION-statements during initialization of the connection.

The variable is parsed according to the Oracle globalization documentation

Example: "NLS_LANG" of AMERICAN_AMERICA.UTF8 will lead to the following statements:



Currently, utPLSQL-cli supports the following sub-commands:

  • run
  • info
  • reporters
  • help

To get more info about a command, use

utplsql <sub-command> -h


utplsql run -h


This is used in all commands as first parameter (though it's optional for info).

Accepted formats:

  • <user>/<password>@//<host>[:<port>]/<service>
  • <user>/<password>@<host>:<port>:<SID>
  • <user>/<password>@<TNSName>

To connect using TNS, you need to have the ORACLE_HOME environment variable set. The file tnsnames.ora must exist in path %ORACLE_HOME%/network/admin The file tnsnames.ora must contain valid TNS entries.

In case you use a username containing / or a password containing @ you should encapsulate it with double quotes ":

utplsql run "my/Username"/"myP@ssword"@connectstring


utplsql run <ConnectionURL> [<options>]


-p=suite_path(s)    - A suite path or a comma separated list of suite paths for unit test to be executed.     
(--path)              The path(s) can be in one of the following formats:
                      Both formats can be mixed in the list.
                      If only schema is provided, then all suites owner by that schema are executed.
                      If -p is omitted, the current schema is used.

--tags=tags         - A comma separated list of tags to run. 
                      Format: --tags=tag1[,tag2[,tag3]]
-f=format           - A reporter to be used for reporting.
(--format)            If no -f option is provided, the default ut_documentation_reporter is used.
                      See reporters command for possible values
  -o=output         - Defines file name to save the output from the specified reporter.
                      If defined, the output is not displayed on screen by default. This can be changed with the -s parameter.
                      If not defined, then output will be displayed on screen, even if the parameter -s is not specified.
                      If more than one -o parameter is specified for one -f parameter, the last one is taken into consideration.
  -s                - Forces putting output to to screen for a given -f parameter.
-source_path=source - path to project source files, use the following options to enable custom type mappings:
-test_path=test     - path to project test files, use the following options to enable custom type mappings:
-c                  - If specified, enables printing of test results in colors as defined by ANSICONSOLE standards. 
(--color)             Works only on reporeters that support colors (ut_documentation_reporter).
-fcode=code         - Override the exit code on failure, defaults to 1. You can set it to 0 to always exit with a success status.

-scc                - If specified, skips the compatibility-check with the version of the database framework.
(--skip-              If you skip compatibility-check, CLI will expect the most actual framework version
-include=pckg_list  - Comma-separated object list to include in the coverage report.
                      Format: [schema.]package[,[schema.]package ...].
                      See coverage reporting options in framework documentation.
-exclude=pckg_list  - Comma-separated object list to exclude from the coverage report.
                      Format: [schema.]package[,[schema.]package ...].
                      See coverage reporting options in framework documentation.
-q                  - Does not output the informational messages normally printed to console.
(--quiet)             Default: false
-d                  - Outputs a load of debug information to console
(--debug)             Default: false

-t=timeInMinutes   - Sets the timeout in minutes after which the cli will abort. 
(--timeout)          Default 60
-D                 - Enables DBMS_OUTPUT in the TestRunner-Session
(--dbms_output)      Default: false

-r                 - Enables random order of test executions
(--random-test-order) Default: false

-seed              - Sets the seed to use for random test execution order. If set, it sets -random to true

Parameters -f, -o, -s are correlated. That is parameters -o and -s are controlling outputs for reporter specified by the preceding -f parameter.

Sonar and Coveralls reporter will only provide valid reports, when source_path and/or test_path are provided, and ut_run is executed from your project's root path.


> utplsql run hr/hr@xe -p=hr_test -f=ut_documentation_reporter -o=run.log -s -f=ut_coverage_html_reporter -o=coverage.html -source_path=source

Invokes all Unit tests from schema/package "hr_test" with two reporters:

  • ut_documentation_reporter - will output to screen and save output to file "run.log"
  • ut_coverage_html_reporter - will report only on database objects that are mapping to file structure from "source" folder and save output to file "coverage.html"
> utplsql run hr/hr@xe

Invokes all unit test suites from schema "hr". Results are displayed to screen using default ut_documentation_reporter.


utplsql info [<ConnectionURL>]


> utplsql info

cli 3.1.1-SNAPSHOT.local
utPLSQL-java-api 3.1.1-SNAPSHOT.123
> utplsql info app/app@localhost:1521/ORCLPDB1

cli 3.1.1-SNAPSHOT.local
utPLSQL-java-api 3.1.1-SNAPSHOT.123


utplsql reporters <ConnectionURL>


> utplsql reporters app/app@localhost:1521/ORCLPDB1

    Generates a Cobertura coverage report providing information on code coverage with line numbers.
    Designed for Jenkins and TFS to report coverage.
    Cobertura Document Type Definition can be found:
    Sample file:

    Generates a HTML coverage report with summary and line by line information on code coverage.
    Based on open-source simplecov-html coverage reporter for Ruby.
    Includes source code in the report.
    Will copy all necessary assets to a folder named after the Output-File

    Generates a JSON coverage report providing information on code coverage with line numbers.
    Designed for [SonarQube]( to report coverage.
    JSON format returned conforms with the Sonar specification:

    Generates a JSON coverage report providing information on code coverage with line numbers.
    Designed for [Coveralls](
    JSON format conforms with specification:

    No description available

    A textual pretty-print of unit test results (usually use for console output)
    Provides additional properties lvl and failed

    Provides outcomes in a format conforming with JUnit 4 and above as defined in:

    Provides test results in a XML format, for clients such as SQL Developer interested in showing progressing details.

    Generates a JSON report providing detailed information on test execution.
    Designed for [SonarQube]( to report test execution.
    JSON format returned conforms with the Sonar specification:

    Provides the TeamCity (a CI server by jetbrains) reporting-format that allows tracking of progress of a CI step/task as it executes.

    Provides outcomes in a format conforming with JUnit version for TFS / VSTS.
    As defined by specs :
    Version is based on windy road junit

    Depracated reporter. Please use Junit.
    Provides outcomes in a format conforming with JUnit 4 and above as defined in:

Using utPLSQL-cli as sysdba

Since 3.1.6 it is possible to run utPLSQL-cli as sysdba by running

utplsql run "sys as sysdba"/pw@connectstring

It is, however, not recommended to run utPLSQL with sysdba privileges.

Enabling Color Outputs on Windows

To enable color outputs on Windows cmd you need to install an open-source utility called ANSICON.

Custom Reporters

Since v3.1.0 you can call custom reporters (PL/SQL) via cli, too. Just call the name of the custom reporter as you would do for the core reporters.

utplsql run hr/hr@xe -p=hr_test -f=my_custom_reporter -o=run.log -s
You can’t perform that action at this time.