Socotra Command Line Tools

Introduction

The Socotra Command Line (CLI) tools are a set of commands to manage deployments, do automated testing, and interact with the Socotra API, all from your terminal.

This document assumes a familiarity with Socotra, and with running command line tools. It also assumes you already have access to a Socotra environment.

Installation

The Socotra CLI tools can be downloaded from NPM.

Install as a globally available tool:

$ npm install -g @socotra/cli

or install as a local package:

$ npm install @socotra/cli

The toolset is made up of a number of individual tools, but the main @socotra/cli package automatically installs all that are available.

Getting Started

There are currently five main tools and one additional utility:

  • CLI Tools:

    • socotra-aux: Inspect, read, and write Auxiliary Data

    • socotra-deploy: Deployment of Socotra product configuration

    • socotra-events: Query and stream events from the Socotra Event Stream API

    • socotra-profile: Securely manage Socotra profiles for use in the other tools

    • socotra-scripts: Securely manage deployment of scripts, query and stream events from the Socotra Scripts API

    • socotra-utils: Miscellaneous Socotra utilities

  • Utilities:

    • tz: Utility for converting milliseconds since the epoch to different formats and timezones.

Each tool has a number of commands within it, such as: socotra-profile ls and socotra-deploy zip.

If you forget what tools are available, running a tool itself will list all available commands within it:

$ socotra-profile

Usage: socotra-profile [options] [command]

Options:
--debug               output debugging info
--ci                  change output when running as a CI process
--no-title            turn off title and banner output
--no-banner           turn off banner output
--no-styling          turn off terminal styling and colours
--no-progress         turn off progress bars and spinners
-V, --version         output the version number
-h, --help            display help for command

Commands:
add [options] <name>  add a Socotra profile to this machine
rm <name>             remove a Socotra profile from this machine
clear                 clear all Socotra profiles from this machine
ls                    list Socotra profiles on this machine
help [command]        display help for command

Note

All tools have a -h or --help flag that can be added to any command to provide additional details.

Tools

Storing Credentials

All tools that interact with a Socotra environment need credentials to do so. There are two ways to pass credentials to each command:

  • Using Socotra profiles to store credentials securely in your system’s keychain. This is recommended for interactive usage.

    $ socotra-deploy list-versions -c my-profile

  • By individually specifying the URL, tenant host name, username, and password with command line flags. This is recommended for use in continuous integration and other such automated pipelines.

    $ socotra-deploy list-versions -a https://api.sandbox.socotra.com -n my-tenant.co.sandbox.socotra.com  -u my-user -p my-password

Note

For the purposes of this guide, we’ll be using a stored profile for all examples.

Profile Tool

As most other tools require credentials to authenticate to a Socotra environment, we’ll start with the socotra-profile tool. This is the recommended way to store credentials on your system, as they will be stored in your OS’s secure keychain.

Note

Depending on your OS, you may be prompted to enter your local password, or approve permissions.

The first thing you’ll want to do is add a profile to contain your credentials.

$ socotra-profile add
Usage: socotra-profile add [options] <name>

add a Socotra profile to this machine

Options:
  -a, --api <uri>            the API URI
  -n, --hostName <hostName>  hostname
  -u, --username <username>  username
  -p, --password <password>  password
  -h, --help                 display help for command

$ socotra-profile add -a https://api.sandbox.socotra.com -n my-tenant.co.sandbox.socotra.com -u my-user -p my-password my-profile

This creates a new profile, named my-profile with the sandbox API url, a hostname of my-tenant.co-sandbox.socotra.com, a username of my-user and a password of my-password.

To list the profiles stored on your system:

$ socotra-profile ls

Loading profiles...
Loaded 1 profile(s):
my-profile:
  api: https://api.sandbox.socotra.com
  host: my-tenant.co.sandbox.socotra.com
  user: my-user

Note

Passwords are never displayed by the profile tool.

To remove the my-profile profile:

$ socotra-profile rm my-profile

And to clear all profiles from your system:

$ socotra-profile clear

Deploy Tool

The next tool we’ll be discussing is socotra-deploy. This provides a set of commands for managing deployment of Socotra product configuration.

Note

For these examples, we’ll be assuming you have a complete tenant configuration stored at ~/my-config

There are two ways to deploy that configuration data. The first is a two step process of socotra-deploy zip to zip the configuration folder, followed by socotra-deploy file to deploy the archive.

$ socotra-deploy zip my-zip.zip --overwrite ~/my-config

This will zip up the contents of ~/my-config and write them to my-zip.zip. The --overwrite flag tells it to overwrite the archive if it already exists on your system, and should only be used when you know that’s safe to do.

$ socotra-deploy file my-zip.zip my-tenant -c my-profile

This will take the resultant zip file, my-zip.zip and deploy it to my-tenant using the specified profile my-profile.

Alternately, this can be done all in one step by deploying the folder directly:

$ socotra-deploy folder my-tenant -c my-profile ~/my-config

This will take the ~/my-config folder, zip it to a temporary file, and deploy that to my-tenant using my-profile, all in one step.

Important

By default, both socotra-deploy zip and socotra-deploy folder operate in development mode. This can be override to production mode by specifying --prod or --mode production.

The socotra-deploy tool also has some support for Product Versioning.

To list deployed product versions:

$ socotra-deploy list-versions -c my-profile
Version Deployed At
1       2022-02-22 14:23:53 -06:00
1       2022-03-07 18:52:49 -06:00
2       2022-03-10 19:14:07 -06:00
✔ Found 3 versions

Note

If a version was repaired, the version number can appear multiple times in the list. Only the last uploaded file for any given version is available for download.

And to download the deployed configuration archive for a given version number:

$ socotra-deploy download-version 1 version-1.zip -c my-profile --overwrite

This will download version 1 and write it to version-1.zip. Like before the --overwrite flag allows overwriting a file that already exists on your system.

Important

socotra-deploy download-version retrieves the last configuration archive that was deployed using the socotra-deploy tool, the Deployments API, or Configuration Studio. It is possible to deploy scripts separately (see socotra-scripts), which does not modify the configuration archive. Using socotra-deploy download-version can retrieve a configuration archive that has out of date scripts within it, in that case.

Scripts Tool

Next up, we’ll cover the socotra-scripts tool. It provides a set of commands for managing deployments of scripts (plugins), and streaming or querying log events via the Scripts API.

While the socotra-deploy tool can deploy an entire tenant configuration, which contains scripts, the socotra-scripts tool can be used to deploy just the scripts folder within that config. This process is considerably faster as it skips loading config files, unpacking tables, and validation. The primary use for this is during development of plugins, to iterate quickly and test changes without the delay of redeploying unchanged configuration each time.

Note

See the Plugins topic for details on how to use the Scripts API.

Note

Scripts are stored as part of a tenant configuration. For the purposes of these examples, we’ll be assuming they’re located in ~/my-config/scripts

To deploy a scripts folder:

$ socotra-scripts upload-folder ~/my-config/scripts my-tenant -c my-profile

Similar to before, this will take the scripts located in ~/my-config/scripts and deploy them to my-tenant using my-profile.

Note

This replaces the entire script set, so be sure the scripts folder you are using includes all scripts files, even if they are unchanged.

Important

This does not modify the configuration zip that can be retrieved with socotra-deploy download-version. Using that tool after deploying scripts can result in downloading an out of date scripts set. Be careful not to overwrite your modified scripts, as there is no way to retrieve them from the tenant.

To stream scripting logs from the Scripts API:

$ socotra-scripts stream -c my-profile

To query scripting logs:

$ socotra-scripts query "search text" -c my-profile

or for a specific event, identified by a request id my-request-id.

$ socotra-scripts event my-request-id -c my-profile

Events Tool

The socotra-events tool provides an interface to stream or query the Event Stream API.

Both tools can be given an optional event name, if omitted all event types are displayed.

$ socotra-events stream -c my-profile

or, for one event type:

$ socotra-events stream policy.create -c my-profile

Querying works similiarly but can take start and end timestamps to look for events in a specific time range.

$ socotra-events query policy.create -c my-profile --start 1641016800000 --end 1643608800000

Auxiliary Data Tool

The socotra-aux Auxiliary Data tool provides a set of operations to inspect and modify auxiliary data.

Note

See the Auxiliary Data Feature Guide for details on using Auxiliary Data.

Note

All Aux Data commands require a locator id. This is an arbitrary string, but often is the locator of a policy or other entity. In these examples, we’ll use the string my-locator.

To list all Aux Data keys for a given locator, along with the key’s UI Type:

$ socotra-aux ls my-locator -c my-profile
Key             UI Type
---             -------
my-key          normal

To retrieve the value of a single aux data record, for a given locator and key:

$ socotra-aux get my-locator my-key -c my-profile
Locator: my-locator
Key:     my-key
UI Type: normal
Value:   some-value

To delete a record, for a given locator and key:

$ socotra-aux delete my-locator my-key -c my-profile

To set the value, for a given locator and key to the string “my-value”:

$ socotra-aux set my-locator my-key my-value -c my-profile --uiType readonly

Value is optional, and if not provided will set the record to null.

The --uiType flag is also optional, and if not provided will default to normal. This applies even when setting the value of an existing record, which may have a different UI Type already set.

If the record already exists, this command will prompt for confirmation before overwriting it. If you’re certain that’s what you want to do, or for using this tool in non-interactive scripts, a --yes flag can be added to skip asking for confirmation.

$ socotra-aux set my-locator my-key my-value -c my-profile --uiType readonly --yes

Finally, socotra-aux edit is a command for interactively editing a record using your terminal’s configured text editor. If the record does not exist, it will create a new one. This is useful for modifying aux data records that are large, or formatted across multiple lines (such as JSON data).

$ socotra-aux edit my-locator my-key -c my-profile

Utilities

Timezone Utility

tz is a utility for converting to and from millisecond epoch timestamps, and between various timezones. This is useful when working with many Socotra APIs, as this is the format used for all timestamps.

Show the current date and time for the local timezone

$ tz

Show the current date with the time set to midnight

$ tz -m

Show the current date at midnight in ISO 8601 format for Australia/Sydney

tz -m -z Australia/Sydney --iso

Show the current date at midnight in ISO 8601 format for America/Los_Angeles

tz -m -z America/Los_Angeles --iso

Show the current date and time for the local timezone converted to America/Los_Angeles

tz -Z America/Los_Angeles

Convert a timestamp to a human readable date

tz 1571103045123

Convert a timestamp to a human readable date in the Australia/Sydney timezone

tz 1571103045123 -Z Australia/Sydney

Show the timestamp for a date in ISO 8601 format

tz 2019-10-15T12:30:45.1234

Show the timestamp for a date in DD/MM/YYYY format

tz -f DD/MM/YYYY 15/10/2019

Show known timezones starting with “America”

tz --listzones America

Miscellaneous Utilities

socotra-utils is a collection of various useful tools for working with Socotra that don’t otherwise fit into the other tool collections. They are all used as sub-commands of the socotra-utils command.

  • Utilities:

    • copy-policy

    • data-dictionary

    • render-document

$ socotra-utils copy-policy -c my-profile --policy 100001234

Retrieves a policy from the system and generates a JSON payload that would create that policy as it currently is in-force.

This is useful to retrieve a policy from one environment and recreate it in another (using Postman, or similar tools), for troubleshooting or other purposes.

$ socotra-utils data-dictionary /path/to/config --output output.csv

Reads a Socotra config directory and generates a data dictionary of all defined fields, field groups, etc.

$ socotra-utils render-document -c my-profile --policy 100001234 --document /path/to/config/document.template.liquid

A helper tool for the Render Policy Document API. Takes a document template liquid and a policy locator and generates that document for that policy, returning the URL to view it, along with any variables assigned during processing of the template.

The document template need not be deployed to the tenant. This is useful for document development and debugging.