Toolbelt Basics

The Toolbelt provides a command line interface (CLI) to the the Aunsight platform by exposing platform API capabilities in the form of discrete commands. The Toolbelt CLI contains over four-hundred terminal commands under one top-level executable file, au2. Each of these commands generally corresponds to a single API call to the Aunsight platform services. Toolbelt thus provides a highly-granular way to interact with Aunsight much like the platform SDKs.

The present article introduces the basics of getting around in the Toolbelt by exploring how to navigate the command groups and use global options that affect all commands. After reading this article, users may wish to learn more about specific functional groupings of commands in one of the detailed guides.

Command Groups

Toolbelt can be invoked on most systems by entering au2 in a terminal prompt. Invoking the top level command without any further arguments will display a list of command groups available at the highest level.

Note

Users who have more than one Toolbelt configuration file may need to invoke the specific shell alias they wish to use.

$ au2
/usr/local/bin/au2 /snapshot/aunsight-toolbelt/index.js <command>

Commands:
  admin         Administrative commands
  context       View user & organization contexts
  data          CRUD datasets
  dataflow      CRUD dataflows
  decode        Custom decode files, QDX, PSV
  dslab         CRUD dslab projects
...

Entering the Toolbelt command with the name of one of the top-level command groups and no further arguments will display the commands under that group.

$ au2 context
/usr/local/bin/au2 /snapshot/aunsight-toolbelt/index.js context <command>

Commands:
  config         Show toolbelt config
  cleanup        Remove local contexts
  list           List available contexts
  managed-token  Managed tokens commands
  renew-token    Renew token
  set            Set a context
  show           Show current context
  token-info     Show token info
  unset          Unset the current context
  whoami         Display current user info

Some commands are grouped three or even four levels into the command hierarchy. To view a list of commands at any level, simply type the complete command group hierarchy to see a list of commands for that group:

$ au2 admin gateway rendezvous pool
/usr/local/bin/au2 /snapshot/aunsight-toolbelt/index.js admin gateway rendezvous
pool <command>

Commands:
  list     List pools
  show     Show pool
  enable   Enable pool
  disable  Disable pool

Help

As with other command line tools, Toolbelt supports a help option (--help or -h). Invoking a command with this option will display information about its usage and options:

$ au2 context set --help
/usr/local/bin/au2 /snapshot/aunsight-toolbelt/index.js context set
<organization> [<project>] [--local]

Options:
  -l, --local  Set context for this session                            [boolean]
  -h, --help   Show help                                               [boolean]

Version Information

To display information about the Toolbelt version itself type au2 --version:

$ au2 --version
1.0.464

To check if this is the latest version of the Toolbelt, compare it to the version string of the latest published version:

$ curl -s https://artifacts.aunalytics.com/toolbelt/Toolbelt-latest/version.txt | grep 'version'
version=Toolbelt-V470

The last three digits of the most recent published version string do not match, so the local version is out of data and the latest version should be installed.

Reporting Options

By default, Aunsight displays all output in a human readable form. Usually this involves some form of tabular layout. For processing output in shell scripts, it is easier to report the results in JSON format. To do this, users can specify the --reporter or -R option.

For example, the following outputs show a command in different formats:

Default behavior: (implied option --reporter human)

$ au2 context list
  50d93f12-0288-4473-8d35-3e8e9bbc1693: Apollo
    ┣ 4a04e481-22ff-472c-a426-ec5d7bc04a16: Docs
    ┣ 0c7c5c23-be72-4918-8e60-f1c1cad6e728: ExampleProject
    ┣ 3355a611-500f-4f56-a031-9ba9682198cf: Test
    ┗ 84f8afb3-e7e1-42de-9add-f734b48bcd04: Test2
  128bf0fa-f05b-43ee-8d8f-cb72dbac7d92: Aunalytics
  757f7864-27d7-4505-98c2-611ed7ad7407: Vishpala
    ┣ bad3270e-919e-44fa-81c4-11d3f35b840b: Linda test 1
    ┗ f9af5723-6e59-43be-9f50-bfddb3da75cc: New Project Test

JSON formatted output: (with --reporter json option specified)

$ au2 -R json context list
{"organizations":[{"id":"757f7864-27d7-4505-98c2-611ed7ad7407","name":"Vishpala","projects":[{"id":"f9af5723-6e59-43be-9f50-bfddb3da75cc","name":"New Project Test"},{"id":"bad3270e-919e-44fa-81c4-11d3f35b840b","name":"Linda test 1"}]},{"id":"128bf0fa-f05b-43ee-8d8f-cb72dbac7d92","name":"Aunalytics","projects":[]},{"id":"50d93f12-0288-4473-8d35-3e8e9bbc1693","name":"Apollo","projects":[{"id":"3355a611-500f-4f56-a031-9ba9682198cf","name":"Test"},{"id":"4a04e481-22ff-472c-a426-ec5d7bc04a16","name":"Docs"},{"id":"0c7c5c23-be72-4918-8e60-f1c1cad6e728","name":"ExampleProject"},{"id":"84f8afb3-e7e1-42de-9add-f734b48bcd04","name":"Test2"}]}]}

The advantage of JSON-formatted output is that it can more easily be manipulated using JSON tools like jq. For example, the same command output run through a simple query returns a filtered list of just the names of the organizations:

$ au2 -R json context list | jq '.organizations[].name'
"Vishpala"
"Aunalytics"
"Apollo"