Getting Started

Prerequisites

Supported platforms:

  • GNU/Linux x86_64 (GLIBC 2.24 and up)

  • Windows (64 bit)

Installation

The Installation of UAC CLI is fairly simple as it is just a single binary for Linux and for Windows.

Step 1: Log in to the Stonebranch Customer Portal. If you do not have a login, you can request one at support@stonebranch.com.

Step 2: Click the Software Downloads link.

Step 3: Click the “UAC Tools” link.

Step 4: Click the package appropriate for your platform.

Step 5: Click Save File and browse to your save location.

step 6: Installation

  • On Linux upload the tar.gz archive on the desired filesystem location and run tar -zxvf <name_of_the_archive>. Make sure the uac binary has execute permissions and the installation folder is part of the PATH.

  • On Windows, similarly unzip the archive and place the extracted binary in the desired location.

Configuration

Creating a Profile

Run the config init command so that it will create a profile file for you. Default profile name is default:

$ uac config init
Please enter UAC URL []: https://stonebranchdev.company.com/
Do you use personal access token? [Y/n]:
Please enter personal access token []: <token>
Config file written. (Path: /home/user/.uac/profiles.yml)

Adding new profile

Run the cofig add command and follow the steps:

$ uac config add
Profile Name: my_profile
Please enter UAC URL []: https://stonebranchdev2.company.com/
Do you use personal access token? [Y/n]:
Please enter personal access token []: <token>
Config file written. (Path: /home/vagrant/.uac/profiles.yml)

Using a Profile

To use a profile pass the global --profile or -p flag with the profile name you want to use uac -p my_profile task list.

Environment Variables

The behavior of uac is affected by the following environment variables.

UAC_CLI_URL

The UAC to controller to connect to when executing commands.

UAC_CLI_TOKEN

Token to use for token bases authentication.

UAC_CLI_PROFILE

Name of profile to use.

UAC_CLI_NO_VERIFY_SSL

Skip SSL verification (values: True, False)

Configuration and precedence

Configuration settings are located in multiple places, such as the profile file or user environment variables, or explicitly declared on the command line as a parameter. Certain locations take precedence over others. Configuration settings take precedence in the following order:

  1. Command line options – Overrides settings in any other location, such as the --profile.

  2. Environment variables – You can store values in your system’s environment variables.

  3. Profile file – The profile file is located at ~/.uac/profiles.yml.

Usage

Synopsis

uac [OPTIONS] <COMMAND> <SUBCOMMAND> [SUBCOMMAND OPTIONS] [PARAMETERS]

Global Options

-p, --profile TEXT

Profile to use for the CLI. The profiles must be added to ~/.uac/profiles.yml. Same functionality as UAC_CLI_PROFILE environemnt variable.

--url TEXT

The Base Universal Controller Endpoint of REST APIs. Same functionality as UAC_CLI_URL environment variable.

--token TEXT

The Universal Controller authentication token. Same functionality as UAC_CLI_TOKEN environment variable.

--no-verify-ssl

Skip SSL Host Verification. Same functionality as UAC_CLI_NO_VERIFY_SSL environment variable when se to True.

-a, --argument-file FILENAME

Enter the arguments from a file. Each argument will be in a new line like key=value without quotes around the value.

-l, --log-level LEVEL

Set logging level, one of DEBUG, INFO, WARNING, ERROR, CRITICAL.

-d, --debug

Enable debug mode.

--version

Show the version and exit.

--help

Show this message and exit.

Examples

Working with tasks

In the example below we show the CRUD capabilities of uac CLI, using tasks as an example. In a similar way you can work with different entities, like credentials or agents, using the appropriate commands.

Most of the bellow commands return JSON output which is ommited for brevity.

List all tasks

$ uac task list
[
    {
        "description": null,
        "name": "Task #1",
        "sysId": "760e337d32384fdca26e8ed774689c39",
        "type": "Universal",
        "version": 7
    },
    {
        "description": null,
        "name": "Task #2",
        "sysId": "038fb0a40804456795d13683d37dd72f",
        "type": "Universal",
        "version": 5
    },
    ...
]

List specific task by name

$ uac task list name="Sleep 30"
[
    {
        "description": "Sleep for 30 seconds.",
        "name": "Sleep 30",
        "sysId": "410d696bc0a801c9017e5dbf756ecbd5",
        "type": "Timer",
        "version": 1
    }
]

List specific task by type (listing only Timer tasks)

$ uac task list type='Timer'
[
    {
        "description": "Wait 20",
        "name": "Wait 20",
        "sysId": "ec94bc821ad141f29ea8fabf9c1f30d3",
        "type": "Timer",
        "version": 1
    },
    ...
]

Get specific task definition by name

$ uac task get taskname="Sleep 30"


{
    "type": "taskSleep",
    "actions": {
        "abortActions": [],
        "emailNotifications": [],
        "setVariableActions": [],
        "snmpNotifications": [],
        "systemOperations": []
    },
    "cpDuration": null,
    "cpDurationUnit": "Minutes",
    ...
}

The task get command optionally takes the -o, --output FILENAME flag which specifies a file to write the task definition to. This file can be used as a template to create new tasks or to update the existing definition.

$ uac task get -o /tmp/mytemplate.json taskname="Sleep 30"

Now let’s update this task, changing it’s name and sleep duration. We see that the JSON elements used for this purpose is name and sleepAmount.

$ uac task update -i /tmp/mytemplate.json name="Sleep 40" sleepAmount=40
{
    "response": "Successfully updated the Timer task with id 410d696bc0a801c9017e5dbf756ecbd5 to version 2.",
    "sys_id": "410d696bc0a801c9017e5dbf756ecbd5"
}

Now let’s update the task to it’s original values

$ uac task update -i /tmp/mytemplate.json name="Sleep 30" sleepAmount=30
{
    "response": "Successfully updated the Timer task with id 410d696bc0a801c9017e5dbf756ecbd5 to version 3.",
    "sys_id": "410d696bc0a801c9017e5dbf756ecbd5"
}

Now let’s use this template to create “Sleep 40” task. Using -s option we can parse the JSON output and retrieve those JSON elements for verification purposes.

$ uac task get taskname="Sleep 30" -s "$.name"
Sleep 30

$ uac task get taskname="Sleep 30" -s "$.sleepAmount"
30

Now let’s create the new task

$ uac task create -i /tmp/mytemplate.json name="Sleep 40" sleepAmount=40 retain_sys_ids=false
{
    "response": "Successfully created the Timer task with id 98444d5792244ce8817a879f4611cc19.",
    "sys_id": "98444d5792244ce8817a879f4611cc19"
}


$ uac task get taskname="Sleep 40" -s "$.name"
Sleep 40

$ uac task get taskname="Sleep 40" -s "$.sleepAmount"
40

Now launch the new task and wait for it’s completion

$ uac task launch -w name="Sleep 40"

{
     "agent": null,
     "businessServices": [],
     "credentials": null,
     "customField1": null,
     "customField2": null,
     "earlyFinish": "false",
     "endTime": "2024-11-25 22:21:21 +0200",
     "executionUser": "ops.admin",
     "exitCode": "0",
     "finishedEarly": "false",
     "finishedLate": "false",
     "instanceNumber": 3,
     "lateFinish": "false",
     "lateStart": "false",
     "launchTime": "2024-11-25 22:20:41 +0200",
     "name": "Sleep 40",
     "operationalMemo": null,
     "outputs": null,
     "progress": 100,
     "queuedTime": "",
     "simulation": false,
     "sourceVersion": 1,
     "startTime": "2024-11-25 22:20:41 +0200",
     "startedLate": "false",
     "status": "SUCCESS",
     "statusDescription": null,
     "sysId": "173219110538078141681B2IY2JU4WTF",
     "taskId": "98444d5792244ce8817a879f4611cc19",
     "taskName": "Sleep 40",
     "triggerId": null,
     "triggerName": null,
     "triggerTime": "",
     "triggeredBy": "Manually Launched",
     "type": "Timer",
     "updatedTime": "2024-11-25 22:21:21 +0200",
     "workflowDefinitionId": null,
     "workflowDefinitionName": null,
     "workflowInstanceId": null,
     "workflowInstanceName": null
 }

Finally let’s delete this newly created task

$ uac task delete taskname="Sleep 40"
{
    "response": "Task deleted successfully."
}

Working with STDIN

In the example helow we showcase the creation of a new task without saving a file with -o option. In this case we pipe the result of one uac command to another:

$ uac task get taskname="Sleep 30"| uac task create -i /dev/stdin name="Sleep 40" sleepAmount=40 retain_sys_ids=false
{
    "response": "Successfully created the Timer task with id f752644908ac497aac3dd9df814950cb.",
    "sys_id": "f752644908ac497aac3dd9df814950cb"
}

$ uac task get taskname="Sleep 40" -s "$.name"
Sleep 40

$ uac task get taskname="Sleep 40" -s "$.name"
Sleep 40

That is particularly useful in the case of update operations where the creation of an input file can be avoided:

$uac task get taskname="Sleep 30"| uac task update -i /dev/stdin name="Sleep 100" sleepAmount=100
{
    "response": "Successfully updated the Timer task with id 410d696bc0a801c9017e5dbf756ecbd5 to version 4.",
    "sys_id": "410d696bc0a801c9017e5dbf756ecbd5"
}

More examples

Running a Report
# download PDF file
uac report run-report report_title="Active Tasks" --format pdf --output report_output.pdf
# download the report in different formats
uac report run-report report_title="Active Tasks" --format json
uac report run-report report_title="Active Tasks" --format tab
uac report run-report report_title="Active Tasks" --format csv
uac report run-report report_title="Active Tasks" --format xml
Obtaining System Information
# Get system information and select the memoryFree field
uac system get -s "$.memoryFree" # JSONPATH notation
Obtaining Metrics Information
# Get metrics and output to a JSON file
uac metrics get -o result.json

# Get metrics and filter for a specific metric
uac metrics get | grep -i 'process_virtual_memory_bytes'