Scripting with Prismatic's CLI Tool

Clicking through a web app is a fine way to get things done, but that's not how I like to roll. I prefer the AWS CLI over their web console, and I like to brew install packages more than clicking through installation GUIs. I know that many of my dev friends feel the same way. While I do need to give credit where credit is due – our Prismatic front-end devs did a fantastic job creating a beautiful front-end web app UI – in this post I'd like to turn our attention towards another way to interact with Prismatic's APIs: our CLI tool, which is called prism.

Let's start by going over some prism basics, like how to download and authenticate the tool, go over some basic usage together, and then we'll write a bash script that takes advantage of prism to update an integration and deploy it to a customer.

Installing Prismatic's CLI tool and logging in

Let's start by installing prism. You will need Node.js installed, and will need to be able to run npm or yarn from the command line. The @prismatic-io/prism package is available on npm and can be installed by running:

npm install --global @prismatic-io/prism
# OR
yarn global add @prismatic-io/prism

After installing, let's verify that we can invoke prism from the command line by running prism --help. You should be greeted with a window detailing all the commands you can run within prism, each of which has multiple subcommands:

If you get an error saying the prism command wasn't found, make sure that your global node_modules/.bin directory is included in your PATH environment variable. Run npm bin to identify your node bin directory, and add that directory to your PATH environment variable with export PATH=$PATH:$(npm bin).

Next, let's authenticate our CLI tool. We can do that by running prism login. Our default web browser will open up and bring us to a Prismatic login page.

After we authenticate, prism will cache an API key for the Prismatic API so we can use it to perform CRUD operations on Prismatic resources.

Basic CLI usage

Getting help

The first thing we should look at is the prism help menu. As noted before, we can type prism --help to get a list of prism commands that we can run. Many commands contain subcommands, which we can see by typing prism [command] --help. For example, to see all of the subcommands that we can run on integrations, we can run prism integrations --help:

$ prism integrations --help
Create an Integration

USAGE
  $ prism integrations:COMMAND

COMMANDS
  integrations:create                Create an Integration
  integrations:delete                Delete an Integration
  integrations:export                Export an integration to a YAML file.
  integrations:fork                  Fork an Integration
  integrations:import                Import an Integration using a YAML definition file
  integrations:list                  List Integrations
  integrations:publish               Publish a version of an Integration for use in Instances
  integrations:required-config-vars  Create a Required Config Variable for an integration
  integrations:steps                 List Steps of an Integration
  integrations:test                  Run a test of an Integration
  integrations:update                Update an Integration's name or description
  integrations:versions              List Integration Versions.

Listing resources

Most resources (customers, integrations, credentials, etc.) have a :list subcommand. Suppose we want to list all of the integrations that we've created. We can run:

$ prism integrations:list
Name                     Description
Test unit conversion     Test unit conversion
Incomplete TODO Items    Pull down TODO items, filter for incomplete items for a specific user, and wr…
AcmeERP Fuel Integration After a rocket is launched, fuel data is sent to this integration via a trigg…
Email Scraper            Scrape email addresses from a posted URL
User List Importer       Import a list of new users from a third-party vendor

List subcommands have optional flags so we can specify which columns are displayed (--columns), if extended information like unique IDs should be printed (--extended), and what format the output should take (—-output {csv,json,yaml}). We can also filter (—-filter) and sort (—-sort) the results. For example, if we want to list the name and ID of our integrations, and output the result in YAML format, we can run:

$ prism integrations:list --columns name,id --output yaml
- name: Test unit conversion
  id: SW50ZWdyYXRpb246YjRlM2MwNTAtM2ZlNy00MTI1LThjYWMtNjg5YmQ1ZWVjMDgy
- name: Incomplete TODO Items
  id: SW50ZWdyYXRpb246ZDk5MWFiZTctZmM2Zi00Zjg0LTlhYjctNzRkZTIxMDgyNmI3
- name: AcmeERP Fuel Integration
  id: SW50ZWdyYXRpb246OTllM2Q0YmQtNWVmZi00ZDBmLThmNjktMDQ3YzkyZmYxYjU3
- name: Email Scraper
  id: SW50ZWdyYXRpb246MmY2YWJiMzItMGE1Zi00MGRlLWFlZWMtYmVkY2QyODAwNzc1
- name: User List Importer
  id: SW50ZWdyYXRpb246NjhiMmY1NGMtODNiZC00MjY5LTk1MDQtNGM5NTI2ZjU5NDZl

Resource IDs and creating resources

Note that each integration we printed has a long unique identifier (those strings starting with SW50Z...). Every Prismatic resource (components, actions, instances, customers, credentials, etc.) has a unique ID. These are helpful, since we can reference a customer and integration by their IDs, and create an instance by passing in those IDs to the instances:create subcommand.

An instance is an integration that has been deployed to a customer. Let's create an instance of our "AcmeERP Fuel Integration" for our customer "Smith Rocket Company" by first finding our customer and integration IDs:

$ prism customers:list --columns name,id
Name                 Id
FTL Rockets          Q3VzdG9tZXI6OWQxYzBmODEtY2Q4My00ZTBhLWE1NGEtMjM5MGQ1MzU4ODJj
Smith Rocket Company Q3VzdG9tZXI6MGE3YzQ3MjQtYmM4NS00YzZkLTk5MWUtODk0NjMzOWNjNmU4

$ prism integrations:list --columns name,id
Name                     Id
Test unit conversion     SW50ZWdyYXRpb246YjRlM2MwNTAtM2ZlNy00MTI1LThjYWMtNjg5YmQ1ZWVjMDgy
Incomplete TODO Items    SW50ZWdyYXRpb246ZDk5MWFiZTctZmM2Zi00Zjg0LTlhYjctNzRkZTIxMDgyNmI3
AcmeERP Fuel Integration SW50ZWdyYXRpb246OTllM2Q0YmQtNWVmZi00ZDBmLThmNjktMDQ3YzkyZmYxYjU3
Email Scraper            SW50ZWdyYXRpb246MmY2YWJiMzItMGE1Zi00MGRlLWFlZWMtYmVkY2QyODAwNzc1
User List Importer       SW50ZWdyYXRpb246NjhiMmY1NGMtODNiZC00MjY5LTk1MDQtNGM5NTI2ZjU5NDZl

Now we'll use the prism instances:create command to create our instance using the IDs we found:

$ prism instances:create \
  --name "AcmeERP Fuel Integration for Smith Rocket Company" \
  --customer Q3VzdG9tZXI6MGE3YzQ3MjQtYmM4NS00YzZkLTk5MWUtODk0NjMzOWNjNmU4 \
  --integration SW50ZWdyYXRpb246OTllM2Q0YmQtNWVmZi00ZDBmLThmNjktMDQ3YzkyZmYxYjU3

SW5zdGFuY2U6NDk1YjFkM2YtYzc5Yy00NWE2LWJjN2MtNDYwODZlODViZDJk

That's it! The ID printed at the end is the ID of the new instance that was created. We could then use that ID to run prism instances:test to test our new instance, or prism instances:deploy to deploy it.

Knitting multiple commands together

At this point we've thrown some command line arguments at a couple of :list subcommands and used output from those commands to create an instance. Let's bring those concepts together into a bash script that does the following:

1. Creates / updates an integration by importing an integration defined in YAML. The command integrations:import is idempotent, so it'll create the integration if it doesn't exist, or update it if it does.
2. Publishes the integration so it's ready for deployment to customers
3. Takes a customer name as a command line argument and identifies the customer's ID by name
4. Creates a new instance of our integration for that customer
5. Deploys and enables the instance that we create

The invocation of our bash script to deploy an integration to customer "Smith Rocket Company" will look like this:

path/to/our/script.sh "Smith Rocket Company"

Here's the entire script. We'll break it down into pieces in a moment:

#!/bin/bash

set -e

# Get the directory of this script; assume progix-acmeerp.yaml is
# saved adjacent to this script file.
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"

# Error out if a customer name was not provided
if [ "$#" -ne 1 ]; then
    echo "Usage:"
    echo "  $ ${0} CUSTOMER_NAME"
    exit 1
fi

# Import our integration definition; capture the integration's ID
INTEGRATION_ID=$(prism integrations:import --path ${DIR}/progix-acmeerp.yaml)

# Publish the integration so it's ready for deployment to customers
prism integrations:publish ${INTEGRATION_ID}

# Get the customer's ID and verify the customer exists
CUSTOMER_NAME=$1
CUSTOMER_ID=$(
    prism customers:list \
        --columns id \
        --no-header \
        --filter "Name=${CUSTOMER_NAME}"
)
if [ "${CUSTOMER_ID}" = "" ]; then
    echo "No such customer '${CUSTOMER_NAME}' found."
    exit 1
fi

# Create a new instance of the integration for the customer
INSTANCE_ID=$(
    prism instances:create \
        --name "AcmeERP integration for ${CUSTOMER_NAME}" \
        --customer ${CUSTOMER_ID} \
        --integration ${INTEGRATION_ID}
)

# Deploy and then enable the instance
prism instances:deploy ${INSTANCE_ID}
prism instances:enable ${INSTANCE_ID}

The first portion of the script is standard bash-isms; we have a shebang line to invoke bash, #!/bin/bash, we set our script to error out if any part of the script errors, set -e, we identify the directory of the script so we can find the integration YAML file relative to our script, DIR=..., and then we have an if block to verify that we receive a single command line argument (the name of the customer we're going to deploy an instance to).

Next, we import an integration that is defined in YAML, and capture the integration's ID into a variable INTEGRATION_ID:

INTEGRATION_ID=$(prism integrations:import --path ${DIR}/progix-acmeerp.yaml)

We then publish the integration by passing the INTEGRATION_ID we captured into the integrations:publish subcommand. At this point, the integration is published and ready to be deployed to customers.

Next we identify our customer's ID by filtering for a customer whose name matches the name that was passed into our script. To do that we pass in a --filter flag to the customers:list command, and specify the --no-header flag so that only an ID is printed. The ID is saved to a variable CUSTOMER_ID. Finally, we make sure that CUSTOMER_ID is not an empty string, which would indicate that no customer was found:

CUSTOMER_NAME=$1
CUSTOMER_ID=$(
    prism customers:list \
        --columns id \
        --no-header \
        --filter "Name=${CUSTOMER_NAME}"
)
if [ "${CUSTOMER_ID}" = "" ]; then
    echo "No such customer '${CUSTOMER_NAME}' found."
    exit 1
fi

Now that we have our CUSTOMER_ID and INTEGRATION_ID, we can create a new instance of our integration for our customer, saving the new instance's ID into a variable INSTANCE_ID:

INSTANCE_ID=$(
    prism instances:create \
        --name "AcmeERP integration for ${CUSTOMER_NAME}" \
        --customer ${CUSTOMER_ID} \
        --integration ${INTEGRATION_ID}
)

Finally, we deploy and enable our instance using the INSTANCE_ID that we captured:

prism instances:deploy ${INSTANCE_ID}
prism instances:enable ${INSTANCE_ID}

Done! We now have a fully deployed and enabled instance of our imported integration. We can pop into the web app and check that everything looks exactly like it would if we had deployed and enabled it there:

More about Prismatic's CLI tool

This was just an introduction to Prismatic's CLI tool. We ended up using just a few of the dozens of subcommands available in prism. Through the CLI you can create and edit users and customers, assign credentials and configuration variables, set up alert monitors, manage billing, and more. Anything you can do in the web app, you can do through the CLI.

For a list of all prism subcommands, check out our CLI docs. As you go through our docs, be sure to click the "Prismatic CLI" tab to see examples of how to use the Prismatic CLI to manage various resources.

Please reach out if you'd like to to talk about scripting away integration tasks – we'd love to chat!