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.

Step 7 (Optional): Set Temporary Directory on Linux

On some Linux systems, users may not have permission to execute files in the default temporary folder (/tmp). In these cases, the CLI requires a different folder for its temporary files.

To fix this, set the TMPDIR environment variable to a folder where you have execute permissions. The simplest way to do this is by adding an alias in your shell profile:

alias uac='TMPDIR=/some/path uac'

Tip:

  • A safe and recommended choice is the folder specified by XDG_RUNTIME_DIR:

alias uac='TMPDIR=$XDG_RUNTIME_DIR uac'

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 Universal Controller (UAC) to connect to when executing commands.

UAC_CLI_TOKEN

Token to use for token based authentication.

UAC_CLI_PROFILE

Name of profile to use.

UAC_CLI_NO_VERIFY_SSL

Skip SSL verification (values: True, False)

UAC_CLI_CA_BUNDLE

Specify the path to a CA Bundle.

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 an argument. 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] [ARGUMENTS]

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.

--ca-bundle

Specify path to a CA Bundle to be used for HTTPS SSL Verification. Same functionality as UAC_CLI_CA_BUNDLE 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.

Specifying Command Arguments

Command arguments represent the input payload required for a command to run. They can be provided in several ways:

  • -i <json_payload.json> — supply arguments from a JSON payload file.

  • -a <argument_file> — supply arguments from a plain argument file.

  • key=value pairs on the command line (e.g. name=NewName).

Input Option (-i / --input)

Several commands accept an input file via the -i / --input option. The usage of that file depends on the command:

  • If the command expects a JSON payload, pass a JSON file (for example, payload.json). The file contents will be used as the request payload.

  • For commands that accept archive inputs, the -i file may be a ZIP or other archive format (check the command help for allowed formats).

When a -i input file is used as a payload (JSON), additional arguments may also be provided on the CLI. Any explicitly provided CLI arguments will be used to overwrite the corresponding fields inside the input payload.

Example:

$ uac resource create -i payload.json name=NewName

If payload.json originally contains {"name": "PayloadName", "retryCount": 1}, the final payload sent will have name=NewName and retryCount=1.

Argument File Option (-a / --argument-file)

The argument file (-a, --argument-file) provides an alternative way to pass arguments. Each argument should be written on its own line using the format key=value. Values must be unquoted, for example:

name=NewName
enabled=true
retries=3

Argument Precedence

The precedence rules when multiple sources provide the same field are:

  1. Argument file (-a) — Highest precedence: values from the argument file.

  2. Explicit CLI arguments (key=value pairs passed on the command line, e.g. name=NewName).

  3. Input file payload (-i) — Lowest precedence: values defined inside the input file are used only if not overridden by the above options.

Example showing precedence:

# payload.json contains: {"name": "PayloadName", "enabled": false}
# args.txt contains:
#   name=FromArgFile
#   timeout=30

$ uac resource create -i payload.json -a args.txt name=NewName enabled=true

Resulting effective values used for the request: - name -> FromArgFile (from argument file, highest precedence)

  • enabled -> true (from explicit CLI argument; argument file didn’t set it)

  • timeout -> 30 (from argument file, has to be one of keys expected to be present in the payload, as it’s not included in the initial payload)

  • any other payload fields not present in -a or CLI remain as in payload.json

Note

Documentation follows standard API conventions by using snake_case for command-line arguments (e.g., business_services, updated_time). However, UAC-CLI provides flexible argument syntax by accepting both snake_case and camelCase formats when attempting to override values present in the -i payload, for user convenience. Argument names are accepted interchangeably when provided on the CLI or in an argument file, and the CLI will normalize/convert names as needed.

This dual support allows users to use their preferred naming convention, while UAC-CLI automatically handles the conversion between formats.

Since get commands return API responses in camelCase format, users often find camelCase argument syntax more intuitive when building upon data they’ve already retrieved, creating a seamless workflow between querying and modifying entities.

Tips and Tricks

Using Output Files to Simplify Object Creation/Modification

When attempting to update values of existing objects, the -o (output) option in combination with a get command can be used to retrieve a constructed payload and simplify the process. The retrieved payload can then be altered and fed back into the CLI to apply changes.

$ uac task get -o task.txt taskid=some_task_id

At this point, users can either directly make changes to task.txt.

$ uac task update -i task.txt
{
    "response": "Successfully updated the Manual task with id 72b4edd45b274712a6847b33f0747909 to version 4.",
    "sys_id": "72b4edd45b274712a6847b33f0747909"
}

Alternatively, changes can also be provided as additional command line arguments:

$ uac task update -i task.txt name=new_name
{
    "response": "Successfully updated the Manual task with id 72b4edd45b274712a6847b33f0747909 to version 5.",
    "sys_id": "72b4edd45b274712a6847b33f0747909"
}

Working with STDIN

Instead of writing intermediate files with the -o option, you can also stream data between commands using standard input/output. This allows one command to pipe directly into another, as seen below:

$ 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

Note

The approaches mentioned above can even be combined, in order to make quick changes with minimal effort, while also avoiding the creation of an intermediary file, as seen below:

$ uac task get taskid=72b4edd45b274712a6847b33f0747909 | uac task update -i /dev/stdin name=new_name
{
    "response": "Successfully updated the Manual task with id 72b4edd45b274712a6847b33f0747909 to version 5.",
    "sys_id": "72b4edd45b274712a6847b33f0747909"
}

Examples

Working with tasks

The following examples demonstrate CRUD operations with the uac CLI, using tasks as an example. A similar approach can be applied to other entities like credentials or agents by using the appropriate commands.

Most commands return JSON output, which is truncated or omitted for brevity.

$ 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 a 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 tasks by type
$ uac task list type='Timer'
[
    {
        "description": "Wait 20",
        "name": "Wait 20",
        "sysId": "ec94bc821ad141f29ea8fabf9c1f30d3",
        "type": "Timer",
        "version": 1
    },
    ...
]
Get a specific task definition
$ uac task get taskname="Sleep 30"


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

The task get command can also use the -o, --output FILENAME flag to save the task definition to a file. This file can be used as a template for creating new tasks or updating the existing task.

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

Use the saved template file to modify task properties. The JSON elements used for this purpose are 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"
}

Revert the task to its 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"
}
Creating a new task from a template

Use the template file to create a new task. Using the -s option, the JSON output can be parsed and specific JSON elements can be retrieved for verification purposes.

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

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

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"
}

Verify task creation:

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

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

Launch the newly created task and wait for its 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
 }
Deleting a task

Finally, delete the newly created task

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

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'