=============== 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 ``. 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: .. code-block:: bash alias uac='TMPDIR=/some/path uac' **Tip:** - A safe and recommended choice is the folder specified by ``XDG_RUNTIME_DIR``: .. code-block:: bash 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 []: 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 []: 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: #. Command line options – Overrides settings in any other location, such as the ``--profile``. #. Environment variables – You can store values in your system's environment variables. #. Profile file – The profile file is located at ``~/.uac/profiles.yml``. ***** Usage ***** Synopsis ~~~~~~~~ .. code-block:: bash uac [OPTIONS] [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 `` — supply arguments from a JSON payload file. - ``-a `` — 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: .. code-block:: bash $ 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: .. code-block:: text 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: .. code-block:: bash # 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. Navigating through commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the ``--help`` option helps understanding commands and their usage. .. code-block:: bash $ uac --help ... ... Options: --version Show the version and exit. -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] -d, --debug Enable debug mode -p, --profile TEXT Profile to use for the CLI. The profiles must be added to ~/.uac/profiles.yml EnvVar=UAC_CLI_PROFILE --url TEXT The Base Universal Controller Endpoint of REST APIs. EnvVar=UAC_CLI_URL --token TEXT The Universal Controller authentication token. EnvVar=UAC_CLI_TOKEN --ca-bundle Specify a CA Bundle to be used for HTTPS SSL Verification. EnvVar=UAC_CLI_CA_BUNDLE --no-verify-ssl Skip SSL Verification. EnvVar=UAC_CLI_NO_VERIFY_SSL -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 --help Show this message and exit. Commands: agent Commands for managing Agents, such as retrieving, updating, and deleting agents agent-cluster Commands related to managing Agent Clusters, including creation, deletion, and listing ... ... Using the ``--help`` option helps undertading the subcommands supported by each command along with available options and agruments .. code-block:: bash $ uac task --help Usage: uac task [OPTIONS] COMMAND [ARGS]... Task management commands, including creating, updating, deleting, and launching tasks. Options: --help Show this message and exit. Commands: create Create a Task delete Delete a Task get Read a Task launch Launch a Task list List Tasks list-advanced List Tasks - Advanced list-workflow-list List All Workflows That a Task Belongs To new Create new tasks from template. update Modify a Task Showing the help message for ``uac task list --help`` command .. code-block:: bash $ uac task list --help Usage: uac task list [OPTIONS] name=value enabled=value type=value business_services=value updated_time_type=value updated_time=value workflow_id=value workflow_name=value agent_name=value description=value tasks=value template_id=value template_name=value Options: -o, --output FILENAME -s, --select TEXT select which field to be returned. JSONPATH --help Show this message and exit. 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. .. code-block:: bash $ uac task get -o task.txt taskid=some_task_id At this point, users can either directly make changes to ``task.txt``. .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ 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 ^^^^^^^^^^^^^^ .. code-block:: bash $ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash $ 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 ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash $ uac task list type='Timer' [ { "description": "Wait 20", "name": "Wait 20", "sysId": "ec94bc821ad141f29ea8fabf9c1f30d3", "type": "Timer", "version": 1 }, ... ] ---------- Get a specific task definition ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash $ 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. .. code-block:: bash $ 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``. .. code-block:: bash $ 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: .. code-block:: bash $ 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. .. code-block:: bash $ uac task get taskname="Sleep 30" -s "$.name" Sleep 30 $ uac task get taskname="Sleep 30" -s "$.sleepAmount" 30 Create the new task: .. code-block:: bash $ 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: .. code-block:: bash $ 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 .. code-block:: bash $ 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 .. code-block:: bash $ uac task delete taskname="Sleep 40" { "response": "Task deleted successfully." } ---------- More examples ------------- Running a Report ^^^^^^^^^^^^^^^^ .. code-block:: bash # 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Get system information and select the memoryFree field uac system get -s "$.memoryFree" # JSONPATH notation Obtaining Metrics Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # 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'