/
Command Line Interface (CLI)

Command Line Interface (CLI)

May 31, 2023

Introduction

The Universal Controller Command Line Interface (CLI) is implemented as a set of functions that perform specific actions in a Universal Controller. The results of the actions are written to the CLI standard output.

The CLI command, uagcmd, executes a function according to information specified in its required and optional Global parameters and function-specific parameters.

CLI Functions

CLI functions perform specific actions in a Universal Controller.

The CLI command, uagcmd, can execute functions on any system that has TCP/IP connectivity to the Universal Message Service (OMS).

The command line syntax for each execution of uagcmd must specify a single CLI function, required / optional Global parameters, and required / optional function-specific parameters. You must use the required Global parameters to connect to OMS Servers and to log on to a Controller (User ID and Password).

(See Pre-6.2.0.0 CLI Functions for a backward-compatible version of this syntax that can be used for pre-6.2.0.0 CLI functions.)

The following information is provided for each CLI Function:

  • Description

  • Command line syntax

  • Function-specific parameters

  • Example

Functions are listed alphabetically, by category, on the following pages:

Agent Functions

Bundle Functions

Import and Export Functions

OMS Server Functions

Password Functions

Resource Functions

Task Functions

Tasks in Workflow Functions

Trigger Functions

Variable Functions

Command Line Syntax

The following command line syntax is used for issuing the CLI command, uagcmd:
 

uagcmd functionGlobal parametersfunction-specific parameter(s)

Command Line Entry

Description

Command Line Entry

Description

uagcmd

CLI command that executes all CLI functions.

function

CLI function that performs a specific action in a Universal Controller.

Global parameters

CLI parameters (required and optional) available for all functions.

function-specific parameter(s)

CLI parameters (required and optional) specific to one or more functions.

For example:
 

uagcmd ops-task-launch -c config.cfg -x encryptedfile.txt task-type=unix task-name=task01

In this example, the required Global Parameters are contained in the config.cfg configuration file.
 

Note

For backward-compatibility, you can exclude uagcmd from the command line for all pre-6.2.0.0 CLI functions.

Special Characters Restrictions

The following restrictions apply to the use of special characters in CLI function parameters.

Special Characters

Restrictions

Examples

Special Characters

Restrictions

Examples

|

Can be used only if enclosed in double quotation marks.

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=A|B
'B' is not recognized as an internal or external command,
operable program or batch file.
 
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A|B"
Task Type parameter not specified, defaulting to ALL.
Successfully launched the Manual task "A|B" with task instance sys_id 14503847946836221302J1Y7WPIV75YF.
opscmd-complete

~

Cannot be used, even if enclosed in double quotation marks.

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A~B"
Parameter CMDVERB contains malformed name/value pair(s).
opscmd-complete

=

Cannot be used, even if enclosed in double quotation marks; prevents a CLI function from running.

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A=B"
uagcmd ops-task-launch usage:
uagcmd ops-task-launch [options] [command_parameters]

+

Can be used with or without double quotation marks.

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A+B"
Task Type parameter not specified, defaulting to ALL.
Successfully launched the Manual task "A+B" with task instance sys_id 14503847946836441301OS0WDEQOH7Y1.
opscmd-complete
 
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=A+B
Task Type parameter not specified, defaulting to ALL.
Successfully launched the Manual task "A+B" with task instance sys_id 14503847946836541302LCVCMLXWPSO0.
opscmd-complete

Restrictions for task-variables= Parameter

None of these special characters identified in Special Characters Restrictions - =, |, +, and ~ - can be use in a task-variables= parameter.

Examples

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V=1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V|1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V+1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete

C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V~1" variable2=V2}
Parameter CMDVERB contains malformed name/value pair(s).
opscmd-complete

Pre-6.2.0.0 CLI Functions

For backward-compatibility, you can exclude uagcmd from the command line for all pre-6.2.0.0 CLI functions:
 

Agent Functions

Import and Export Functions

Password Functions

Resource Functions

Task Functions

Trigger Functions

Variable Functions

Return Codes

The following table identifies all return codes that can be returned in response to a function:

Return Code

Description

Return Code

Description

0

Completed successfully.

1

Configuration error (incorrect command line or configuration file entries).

2

Error processing the request.

Supported Platforms

For all supported platforms, the CLI is included in the Universal Agent 7.2.x package.
 

UNIX

The CLI functions are installed in the following directory:

  • /CLI_HOME/bin

Replace CLI_HOME with the directory in which the Agent components are installed.

Windows

The CLI functions are installed in the following directory:

  • DRIVE:\CLI_HOME\bin

Replace:

  • DRIVE with the drive they are installed on. Add the appropriate directory for your O/S to your PATH environment variable in order to execute the functions without specifying their full path name.

  • CLI_HOME with the directory in which the Agent components are installed.

Note

Do not use fully qualified file names (that is, with the .exe extension) in CLI for Windows parameters; an error will occur.

z/OS

The CLI is implemented with a single program, UAGCMDZ. UAGCMDZ (with alias OPSCMDZ) is installed in the SUNVLOAD library as part of the Universal Agent for z/OS Installation package.
 
See Using the CLI for z/OS for detailed information on using the CLI in a z/OS environment.

CLI Login

User Restriction

You can be restricted from logging in to the CLI either of two ways:

  1. The system level default for CLI access, specified by the System Default Command Line Access Universal Controller system property, has been set to No, and the Command Line Access field in the User Details for your user account is set to -- System Default --."

  2. The Command Line Access field in the User Details for your user account is set to No, which overrides the System Default Command Line Access value.

If either restriction is in place, the following error message will display when you issue a CLI command:

User <your user name> not permitted to use the command line interface. Please check with your administrator.

To remove the restriction, the system administrator must either:

  • Set the System Default Command Line Access property to Yes and set the Command Line access field on the User Definition screen for your user account to -- System Default --.

  • Set the Command Line access field on the User Definition screen for your user account to Yes.

Password Expiration

While a password is expired, CLI access will be prohibited until the password has been changed.

Note

Password expiration is not applicable to LDAP authenticated users.

Global Parameters

The CLI provides the following Global parameters for use with any CLI function:

Parameter

Required

Optional

Parameter

Required

Optional

CA Certificate List



Configuration File



CRL File



Encrypted File