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.

Warning

Upgrading from a previous version? After replacing the binary you must run uac config migrate if you have an existing ~/.uac/profiles.yml. The new version prefers ~/.uac/config.yml and will warn on every invocation until you migrate.

$ uac config migrate

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 to create the config file with a default profile:

$ uac config init
Please enter UAC URL []: https://stonebranchdev.company.com/uc/
Please enter personal access token []: <token>
Config file written. (Path: /home/user/.uac/config.yml)

Viewing the configuration

Run the config get command to print the current configuration. Sensitive values such as tokens are masked:

$ uac config get
version: 1.0.0
output_options:
  default_stdout_format: json
profiles:
  default:
    url: https://stonebranchdev.company.com/uc/
    token: '***'

Adding a new profile

Run the config add-profile command and follow the steps:

$ uac config add-profile
Profile Name: my_profile
Please enter UAC URL []: https://stonebranchdev2.company.com/uc/
Please enter personal access token []: <token>
Config file written. (Path: /home/user/.uac/config.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.

Config File

The UAC CLI stores its configuration in ~/.uac/config.yml. The file is created by uac config init.

Invalid values produce a clear error message pointing to the offending field.

Full file structure:

version: 1.0.0
output_options:
  default_stdout_format: json
  table_settings:
    max_column_width: 50
    show_lines: false
    box: rounded
    expand: false
    padding: 0
  table_columns:
    task list: [name, type, version]
    trigger list: [name, type, status]
profiles:
  default:
    url: https://your-uac-url/uc/
    token: your-token-here
  staging:
    url: https://staging-uac/uc/
    token: another-token

Output Options

Controls the default output behaviour for commands that support the --format option.

default_stdout_format

Default output format when --format is not passed on the command line. Accepted values: json (default), table.

table_settings

Controls the appearance of table output. All fields are optional and fall back to the defaults shown below.

max_column_width (default: 50)

Maximum character width per column. Content is truncated beyond this.

show_lines (default: false)

Show horizontal lines between rows.

box (default: rounded)

Border style. One of: rounded, simple, minimal, heavy, markdown, ascii, none.

expand (default: false)

Stretch the table to fill the full terminal width.

padding (default: 0)

Spaces of padding inside each cell.

table_columns

Sets the default column list for specific commands in table output. The key is the full command path (e.g. task list, connection database list) and the value is a list of field names. Dot notation is supported for nested fields (e.g. name.label). These are applied when no --columns flag is passed.

table_columns:
  task list: [name, type, version, status]
  agent list: [name, hostName, status]
  trigger list: [name, type, nextFireTime]

Migrating from profiles.yml

Earlier versions of UAC CLI used ~/.uac/profiles.yml. If this file is present without a config.yml, each CLI invocation will print a deprecation warning:

Warning: ~/.uac/profiles.yml is deprecated. Run `uac config migrate` to migrate to the new config.yml format.

Run the migration command to create config.yml from your existing profiles.yml:

$ uac config migrate
Migrating /home/user/.uac/profiles.yml → /home/user/.uac/config.yml
Migration complete.

The original profiles.yml is left intact after migration.

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. Config file – The config file is located at ~/.uac/config.yml.

Usage

Synopsis

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

Global Options

-p, --profile TEXT

Profile to use for the CLI. Profiles are stored in ~/.uac/config.yml. Same functionality as UAC_CLI_PROFILE environment 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.

Output Formatting

By default, all commands return JSON output. For list commands, the output can also be displayed as a formatted table using the --format / -f option.

Format Options

The following options control output formatting on list commands:

-f, --format [json|table]

Set the output format. Defaults to output_options.default_stdout_format in config.yml (json if not set).

-c, --columns TEXT

Comma-separated list of fields to display in table columns. Raises an error if a field does not exist in the response.

Both of the following are equivalent:

$ uac task list --format=table
$ uac task list -f table

Example — default JSON output:

$ uac task list name="Sleep*"
[
    {
        "name": "Sleep 30",
        "type": "Timer",
        "version": 1,
        ...
    }
]

Example — table output:

$ uac task list name="Sleep*" --format=table
╭──────────┬─────────────┬───────┬─────────╮
│ Name     │ Description │ Type  │ Version │
├──────────┼─────────────┼───────┼─────────┤
│ Sleep 30 │             │ Timer │ 1       │
├──────────┼─────────────┼───────┼─────────┤
│ Sleep 40 │             │ Timer │ 1       │
╰──────────┴─────────────┴───────┴─────────╯

Each list command has a set of default columns for table output. These defaults can be overridden using the --columns (-c) option.

Customizing Table Columns

Use -c / --columns to specify which fields appear in the table and in what order. Fields are provided as a comma-separated list.

$ uac agent list -f table -c "name,type,version,status"
╭──────────┬────────────┬─────────┬─────────╮
│ Name     │ Type       │ Version │ Status  │
├──────────┼────────────┼─────────┼─────────┤
│ MyAgent  │ Linux/Unix │ 7.9.2.0 │ Active  │
├──────────┼────────────┼─────────┼─────────┤
│ WinAgent │ Windows    │ 7.2.0.0 │ Offline │
╰──────────┴────────────┴─────────┴─────────╯

Field names are case-insensitive and matched against the JSON response keys.

Nested Fields

Some API responses contain nested objects. Use dot notation to access nested values.

For example, uac user list-preferences returns items structured like this:

$ uac user list-preferences username="ops.admin"
[
    {
        "name": {
            "label": "Activity Monitor Automatically",
            "value": "uc.activity.monitor_automatically"
        },
        "value": "No"
    },
    {
        "name": {
            "label": "Activity Refresh Rate",
            "value": "uc.activity.refresh_rate"
        },
        "value": "10 seconds"
    },
    ...
]

Using -c name.label,value extracts the nested label key and the top-level value field:

$ uac user list-preferences username="ops.admin" -f table -c name.label,value
╭────────────────────────────────────────────┬──────────────────────╮
│ Label                                      │ Value                │
├────────────────────────────────────────────┼──────────────────────┤
│ Activity Monitor Automatically             │ No                   │
├────────────────────────────────────────────┼──────────────────────┤
│ Activity Refresh Rate                      │ 10 seconds           │
╰────────────────────────────────────────────┴──────────────────────╯

The column headers reflect exactly what was passed to -c.

Columns that resolve to a list or dict value are rendered as their raw string representation.

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.

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 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'