Scripting with Prismatic's CLI Tool

This post refers to an earlier version of Prismatic. Consult our docs on the Prismatic CLI tool or contact us if you'd like help with any of the topics addressed in this post.
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:
- 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. - Publishes the integration so it's ready for deployment to customers
- Takes a customer name as a command line argument and identifies the customer's ID by name
- Creates a new instance of our integration for that customer
- 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!
About Prismatic
Prismatic is the integration platform for B2B software companies. It's the quickest way to build integrations to the other apps your customers use and to add a native integration marketplace to your product. A complete embedded iPaaS solution that empowers your whole organization, Prismatic encompasses an intuitive integration designer, embedded integration marketplace, integration deployment and support, and a purpose-built cloud infrastructure. Prismatic was built in a way developers love and provides the tools to make it perfectly fit the way you build software.
Get the latest from Prismatic
Subscribe to receive updates, product news, blog posts, and more.