Installing and authenticating the Orchestration CLI

You can download the Orchestration CLI package from the Download Center of the UI, by selecting one of the available packages according to the operating system on which you want to use the Orchestration CLI:

Orchestration CLI .zip package

Download the Orchestration CLI .zip package, then extract the files in a directory.

Orchestration CLI .rpm package

Download the Orchestration CLI .rpm package, then install the Orchestration CLI by running the following command:

rpm -i <downloaded_file>.rpm

Orchestration CLI .deb package

Download the Orchestration CLI .deb package, then install the Orchestration CLI by running the following command:

dpkg -i <downloaded_file>.deb

You can also download Orchestration CLI by opening the following URL:

https://hostname:port_number/twsd/api/v2/executable

Where:

hostname

The hostname of the gateway microservice.

port_number

The valid port exposed for API gateway. The default port is 443.

The Orchestration CLI is now ready for use.

After you have downloaded and extracted the required files for Orchestration CLI, you need to configure the config.yaml extension file by any source code editor. The config.yaml file contains mandatory and optional fields. To create the config.yaml file, run the Orchestration CLI file using the command prompt.

1. Navigate to the directory where you have extracted the files for Orchestration CLI or where you have installed the Orchestration CLI.
2. Run Orchestration CLI from the command line.
   Note: For Windows, you can also use PowerShell to run the file.
3. Type ocli plan sc as command, and then press enter to create the config.yaml file. You can run any plan or model commands to create the config.yaml file.

   In Windows operating system, the config.yaml file is created at c:\Users\user_name\.OCLI.

   In Unix operating systems, the config.yaml file is created at home/user_name/.OCLI.

   Note:

   In Mac, after running the command, you must override the security settings to install Orchestration CLI. For more information, see Overriding security settings in Mac.

4. Open the config.yaml file by using any source code editor.
5. Perform the following actions in the config.yaml file.

   Enter valid details for the mandatory fields. If required, you can also specify the optional fields.

   Table 1. Mandatory fields

   Option	Action
   connection
   host	Enter the host name or IP address of the remote engine that you want to use.
   port	Enter the port number of the remote engine that you want to use.
   jwt	When the connection is established for the first time, this field is filled in automatically. For more information, see Authenticating Orchestration CLI using API Keys .

   Table 2. Optional fields

   Option	Actions
   lang	You can use this option to specify any one of the supported languages. The following languages are supported in Orchestration CLI: Brazilian Portuguese (pt_BR) English (en, the default value) French (fr_FR) German (de_DE) Japanese (ja_JP) Important: Ensure that the recent version of powershell is installed on Windows operating system to view the content in the selected language.
   dateformat	The date format is specific to the commands you run on Orchestration CLI. The default format is ymd. If you do not specify any format the default one is applied.
   current_folder	Specify the path to any folder that will be taken as an absolute path, when you run the commands. The default value is "/".
   default workstation	You can specify a workstation as default for Orchestration CLI model item definitions. The workstation mentioned is used as the reference, if you do not specify any workstation in an item definition. The default value is TEST_AGENT.
   local_timezone	You can use this option to specify the timezone. If not, the time zone of the operating system is referred. The supported formats are: The extended form "area/city". For example, "America/New_York” for EST. The 3 character notation, for example ECT (European Central Time).
   user	You can add a specific username to run the submit docommand as a different user in Orchestration CLI.
   model
   format	You can use this option to set up the format for Orchestration CLI. Specify any one of the following formats. The default value is YAML. JSON schedlang YAML For more information, see Managing multiple formats.
   logging
   level	You can use this option to filter the log messages that are retrieved in the ocli.log file. When you set a value, all the messages equal to that severity and above are sorted. The default value is info. To view the file, navigate to C:\Users\user_name\.OCLI\logs. You can enter any one of the following message types. The message types are listed from lower to higher severity. info: Any additional information which is not tied to the current task or action. trace: Messages that provides information about the application flow. debug: Informational messages that are useful to troubleshoot the application. warning: Messages related to user actions that will have unexpected or unwanted consequences. error: Messages related to errors or critical failures that may block the users to proceed further until the issue is resolved. fatal: Messages related to errors that will cause the Orchestration CLI to close without saving any data. panic: Messages related to errors that will cause the Orchestration CLI to close without saving any data. The error is similar to a fatal error and the only difference is the way the application is closed.
   redirect_to	You can use this option to change the location of the log file. The default location is c:\Users\user_name\.OCLI\logs. You can use this option to change the location of the log file. The default location is /home/user_name/.OCLI/logs.
   file_size	You can specify the maximum size of the log file in Mega Bytes(MB). The default value is 10.
   backup_files	You can specify the number of log files which you want to save. The default value is 3.
   connection
   contextroot	You can specify the endpoint that connects with the server. The default value is /twsd/cli.
   protocol	Enter the protocol that you want to use to connect to the remote engine. The default value is https.
   insecure	Enter true, to ignore the host name error on SSL certificate. The default value is false.
   proxy	Specify the proxy IP address, if you are using a proxy server.
   proxyport	Specify the port of the proxy server.
   proxyuser	Provide the user name of the proxy account, if authentication is required.
   proxypassword	Provide the proxy account password.
   timeout	You can use this option to specify the maximum time in milliseconds to display the timeout error message. The default value is 3600.
   show_warnings	If you do not want to receive any warnings when there is an internet connection failure, set the option to false. The default value is true.
   compatibility
   show_copyright_header	If you do not want the copyright content to be displayed when you run a command, set the option to false. The default value is true.

6. Save the config.yaml file.

   Results:

   You have successfully configured Orchestration CLI.

   Note: Orchestration CLI generates temporary files inside the default temporary folder of the operating system. Ensure all Orchestration CLI users have read and write permissions on that temporary folder.

To install Orchestration CLI for the first time in your machine, you must override the system settings. When you run the command to create the config.yaml file, an error message is displayed stating that Apple is unable check the application for malicious software. It is still safe to install Orchestration CLI, and you must override the settings in your machine to proceed. Complete the following steps to override the settings.

1. On your machine, navigate to System Preferences > Security & Privacy.

   The Security & Privacy pane is displayed. You can see the Allow Anyway button with the following message:

   "ocli" was blocked from use because it is not from an identified developer.

2. Click Allow Anyway.
   Note: This button is available for about an hour after you try to run the application.

   The application is now saved as an exception to your security settings and you can open it in the future using the command line, just as any other authorised application.

   You can now proceed from Step 3.

When you connect to HCL Universal Orchestrator using Orchestration CLI for the first time, you need to authenticate the connection using API Keys.

1. Create valid credentials in an authentication or authorization provider that uses the open protocol standard OpenID Connect.
2. Configure HCL Universal Orchestrator to specify the instance where the authentication or authorization provider is running. For more information, see Deploying and Administrating.
3. Navigate to the directory where you have extracted the files for Orchestration CLI or where you have installed the Orchestration CLI.
4. Run Orchestration CLI from the command line.
   Note: For Windows, you can also use PowerShell to run the file.
5. Type any model or plan command.
   Example:

   ocli model list folder @

   An error message with a web link to create the API Key is displayed.

6. Open the web link using any web browser.

   The login page of the authentication provider that you configured is displayed.

7. Enter the username and password for the authorization provider.

   A message is displayed to indicate that the API Key has been successfully generated. This API Key gets automatically updated in the config.yaml file.

   Results:

   You have successfully established a connection with HCL Universal Orchestrator from Orchestration CLI.