Socotra Command Line Tools
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.
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.
There are currently five main tools and one additional utility:
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
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
If you forget what tools are available, running a tool itself will list all available commands within it:
Usage: socotra-profile [options] [command]
--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
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
All tools have a
--help flag that can be added to any command to provide additional details.
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
For the purposes of this guide, we’ll be using a stored profile for all examples.
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.
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
-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
To list the profiles stored on your system:
$ socotra-profile ls
Loaded 1 profile(s):
Passwords are never displayed by the profile tool.
To remove the
$ socotra-profile rm my-profile
And to clear all profiles from your system:
$ socotra-profile clear
The next tool we’ll be discussing is
socotra-deploy. This provides a set of commands for managing deployment of Socotra product configuration.
For these examples, we’ll be assuming you have a complete tenant configuration stored at
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
--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
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-profile, all in one step.
By default, both
socotra-deploy zip and
socotra-deploy folder operate in development mode. This can be override to production mode by specifying
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
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.
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.
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.
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.
See the Plugins topic for details on how to use the Scripts API.
Scripts are stored as part of a tenant configuration. For the purposes of these examples, we’ll be assuming they’re located in
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
This replaces the entire script set, so be sure the scripts folder you are using includes all scripts files, even if they are unchanged.
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
$ socotra-scripts event my-request-id -c my-profile
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
socotra-aux Auxiliary Data tool provides a set of operations to inspect and modify auxiliary data.
See the Auxiliary Data Feature Guide for details on using Auxiliary Data.
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
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
To retrieve the value of a single aux data record, for a given
$ socotra-aux get my-locator my-key -c my-profile
UI Type: normal
To delete a record, for a given
$ socotra-aux delete my-locator my-key -c my-profile
To set the value, for a given
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
--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
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
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
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
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
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
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 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.