How to Use Prismatic's CLI Tool
The Prismatic CLI tool allows you to interact with the Prismatic API programmatically so you can build, deploy, and support integrations from the command line. The CLI tool is built using the Prismatic API, so any action that can be completed through the web app or API can be completed through the CLI tool, as well.
#
Installing the CLI ToolPrismatic's CLI tool, prism
, is available at https://www.npmjs.com/package/@prismatic-io/prism and can be installed using npm
or yarn
:
npm install -g @prismatic-io/prism# ORyarn global add @prismatic-io/prism
Prism's source code is available on GitHub, and serves as a great example for how to wrap the Prismatic API.
#
Authenticating with the CLI ToolOnce prism
has been installed login by typing:
prism login
This will open a web browser for you to authenticate with your Prismatic credentials.
Once you authenticate, your CLI tool will store an authentication token for subsequent prism
commands.
To verify that you are logged in you can run prism me
to see information about your user.
prism me
Name: Alex CooperEmail: alexander.cooper@progix.ioOrganization: Progix SoftwareEndpoint URL: https://app.prismatic.io
If you want to view the authentication token that your CLI tool uses, run prism me:token
.
prism me:tokeneyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik5lVV9aYzFNdFRrSE93bXB1T2ZlUCJ9.eyJodHRwczovL3ByaXNtYXRpYy5pby9lbWFpbCI6InRlc3QudXNlckBlbWFpbC5jb20iLCJodHRwczovL3ByaXNtYXRpYy5pby9sYXN0X2xvZ2luIjoiMzAyMS0wMS0wMVQwMDowMDowMC4wMDFaIiwiaXNzIjoiaHR0cHM6Ly9wcmlzbWF0aWMtaW8udXMuYXV0aDAuY29tLyIsImF1ZCI6WyJodHRwczovL3ByaXNtYXRpYy5pby9hcGkiLCJodHRwczovL3ByaXNtYXRpYy1pby51cy5hdXRoMC5jb20vdXNlcmluZm8iXSwiaWF0IjoxNjEyMjA4NjQyLCJleHAiOjE2MTIyOTUwNDIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwgb2ZmbGluZV9hY2Nlc3MifQ.iKQWx95vUWTxF62O3-mZFqHPgfapH7TQjsy-BunqWWDJrhk88byJpJQYy__hJE779qAahkEtZD914zgpZ8UnjGW0i_PUcCf5nZsDJBR-jfTEARCLmeVYge3Hy40BAFzj3eCcCouDFqxMNaD3oeXSjfizO9Cy_P-XKEkDdIOJ-rk
To clear your token from memory and log out, run prism logout
.
Logging in to other regions
By default your data is stored in the US commercial region and prism
authenticates against that region.
If your enterprise plan includes additional regions or private cloud, you will need to instruct prism
to point to that region.
See Integrations in Multiple Regions.
#
Running CLI Commands and Getting HelpAll Prismatic CLI commands generally follow the form prism COMMAND
.
For example, you can run prism customers:list
to list all of your customers, or prism integrations:create
to create an integration.
A full list of prism
commands can be found on the Prismatic CLI Command Reference page.
Typing prism --help
will also list top-level commands that you can run.
prism --help
Build, deploy, and support integrations in Prismatic from the comfort of your command line
VERSION @prismatic-io/prism/4.2.6 darwin-arm64 node-v14.17.6
USAGE $ prism [COMMAND]
TOPICS alerts Manage Alerting resources authorization-methods List Authorization Methods that Components can use components Manage, create, and publish Components customers Manage Customers executions Fetch results of Instance executions or Integration test runs instances Manage Instances integrations Manage and import Integrations logs List Log Severities for use by Alert Triggers me Print your user profile information organization Manage your Organization
COMMANDS help Display help for prism. login Log in to your Prismatic account logout Log out of your Prismatic account me Print your user profile information
To see subcommands of top level commands, you can type prism COMMAND --help
.
For example, to see what you can do with customers run
prism customers --help
Manage Customers
USAGE $ prism customers:COMMAND
TOPICS customers:credentials Manage Customer Credentials customers:users Manage Customer Users
COMMANDS customers:create Create a new Customer customers:delete Delete a Customer customers:list List your Customers customers:update Update a Customer
For a list of all required arguments of a command, type prism COMMAND:SUBCOMMAND --help
.
For example, to see the required arguments to create a customer, run
prism customers:create --help
Create a new Customer
USAGE $ prism customers:create -n <value> [-d <value>]
FLAGS -d, --description=<value> longer description of the customer -n, --name=<value> (required) short name of the new customer
DESCRIPTION Create a new Customer
#
Listing ResourcesAll types of prismatic resources (customers, components, integrations, instances, actions, etc.) have :list
subcommands.
By default, list commands show basic information about the resource, like name and description, but additional information like resource ID can be displayed.
You can optionally select exactly what attributes of resources you want to list, you can filter the results, and you can format the results as CSV, JSON, or YAML.
prism components:list
Label Public Description Version Category ─────────────────────── ────── ───────────────────────────────────────────────────────────────────────────────────────────── ─────── ────────────────────── Acme ERP false Interact with Acme ERP's inventory and customer systems 2 null Airtable true Manage items (records) in an Airtable Base 2 Data Platforms Amazon DynamoDB true Create, update, fetch, or delete items in an Amazon (AWS) DynamoDB database 5 Data Platforms Amazon S3 true Manage files within an Amazon (AWS) S3 bucket 34 Data Platforms Amazon SES true Send Emails through Amazon (AWS) SES 5 Application Connectors Amazon SNS true Manage subscriptions, topics, and messages within Amazon (AWS) SNS 7 Data Platforms Amazon SQS true Send, receive and manage messages within an Amazon (AWS) SQS queue 10 Data Platforms AMQP true Send and receive messages on an AMQP-based message broker 5 Data Platforms
#
Listing Resource IDsAll Prismatic resources have unique IDs.
IDs are not displayed by default through list
subcommands, but can optionally be displayed with the --extended
flag.
For example, to see IDs for components, run
prism components:list --extended
Id Key Label Public Description Version Category ──────────────────────────────────────────────────────────────── ─────────────────────── ─────────────────────── ────── ───────────────────────────────────────────────────────────────────────────────────────────── ─────── ────────────────────── Q29tcG9uZW50OjI3ZWM4ODlmLTI1ODUtNDFiMy05MDdlLWI2YWExNTg5ZGNhNA== acmeerp Acme ERP false Interact with Acme ERP's inventory and customer systems 2 null Q29tcG9uZW50OmVkMjcwNmExLThiMTEtNDI0YS05MjM0LTgzZjU4NDBmNzA3NQ== airtable Airtable true Manage items (records) in an Airtable Base 2 Data Platforms Q29tcG9uZW50Ojg3NzE3YThhLTFiODktNDY5My1hYmZlLWRjY2VkMjMxM2RlZg== aws-dynamodb Amazon DynamoDB true Create, update, fetch, or delete items in an Amazon (AWS) DynamoDB database 5 Data Platforms Q29tcG9uZW50OjE3NmRjYWU3LWEzMzktNDQ2NC1iYmJkLTU4ODllNzdmOWJjYQ== aws-s3 Amazon S3 true Manage files within an Amazon (AWS) S3 bucket 34 Data Platforms Q29tcG9uZW50Ojg3NjlhODE1LTY1OTEtNDliZC1hMGQ5LTNhMWNlYjUxZmZkYQ== aws-ses Amazon SES true Send Emails through Amazon (AWS) SES 5 Application Connectors Q29tcG9uZW50OjNkMzFkYjYxLWFlYzItNDRjZS05NGNkLTVhZWJjMjIxNjlhZg== aws-sns Amazon SNS true Manage subscriptions, topics, and messages within Amazon (AWS) SNS 7 Data Platforms Q29tcG9uZW50OmQ5ZmJkYzViLTFhMGUtNDRlMS1hNDcxLTNjMWE0NzFhYzAwNQ== aws-sqs Amazon SQS true Send, receive and manage messages within an Amazon (AWS) SQS queue 10 Data Platforms Q29tcG9uZW50OmFmYjNlMTNmLTg0NDctNGJmMC05MWIyLTAxNGQ1OTliYThkYg== amqp AMQP true Send and receive messages on an AMQP-based message broker 5 Data Platforms
#
Configuring Columns of a List to DisplayYou can optionally choose which attributes of a resource to display using the --columns
flag.
For example, to get the Key, Label, and ID of all components, you can run
prism components:list --columns key,label,id
Key Label Id ──────────── ─────────────── ──────────────────────────────────────────────────────────────── acmeerp Acme ERP Q29tcG9uZW50OjI3ZWM4ODlmLTI1ODUtNDFiMy05MDdlLWI2YWExNTg5ZGNhNA== airtable Airtable Q29tcG9uZW50OmVkMjcwNmExLThiMTEtNDI0YS05MjM0LTgzZjU4NDBmNzA3NQ== aws-dynamodb Amazon DynamoDB Q29tcG9uZW50Ojg3NzE3YThhLTFiODktNDY5My1hYmZlLWRjY2VkMjMxM2RlZg== aws-s3 Amazon S3 Q29tcG9uZW50OjE3NmRjYWU3LWEzMzktNDQ2NC1iYmJkLTU4ODllNzdmOWJjYQ== aws-ses Amazon SES Q29tcG9uZW50Ojg3NjlhODE1LTY1OTEtNDliZC1hMGQ5LTNhMWNlYjUxZmZkYQ== aws-sns Amazon SNS Q29tcG9uZW50OjNkMzFkYjYxLWFlYzItNDRjZS05NGNkLTVhZWJjMjIxNjlhZg== aws-sqs Amazon SQS Q29tcG9uZW50OmQ5ZmJkYzViLTFhMGUtNDRlMS1hNDcxLTNjMWE0NzFhYzAwNQ== amqp AMQP Q29tcG9uZW50OmFmYjNlMTNmLTg0NDctNGJmMC05MWIyLTAxNGQ1OTliYThkYg==
#
Filtering List OutputYou can filter the output that a :list
subcommand displays using a --filter
flag.
For example, to only show the component with the key "aws-s3", run
prism components:list --filter 'key=^aws-s3$'
Label Public Description Version Category ───────── ────── ───────────────────────────────────────────── ─────── ────────────── Amazon S3 true Manage files within an Amazon (AWS) S3 bucket 34 Data Platforms
Filter uses regex
The --filter
flag uses regex pattern matching, hence the "start of string" ^
character, and "end of string" $
character.
In a bash script, you can combine the --filter
flag with the --columns
and --no-header
flags to get the ID of a specific resource
AWS_S3_COMPONENT_ID=$(prism components:list --filter 'key=aws-s3' --no-header --columns id)echo ${AWS_S3_COMPONENT_ID}Q29tcG9uZW50OjJlMDcyMGU4LTFjNTUtNDY1Ni04NzY0LTI1N2RmZDVhNTE3Mw==
#
Formatting List OutputLists can be optionally formatted as CSV, JSON, or YAML using the --output
flag.
This flag can be combined with the --columns FORMAT
and --filter
flag, as well.
For example, if you want id and key of all components in CSV format, run
prism components:list --output csv --columns id,key
Id,KeyQ29tcG9uZW50OjNiODQ1NGVkLTE5MjEtNGYxNS04MDhmLTBlZjkxNDEzNGRhZA==,airtableQ29tcG9uZW50OjE5YWYzMzQzLTU2OWQtNDY0Yy1iNTAwLWUzM2RhNjg3YmQxYQ==,aws-dynamodbQ29tcG9uZW50OjQ1ZGVkMzEyLTE2ZmUtNGY0Mi04OWVlLWZhOTIzNTQ0ZDEyYQ==,aws-s3Q29tcG9uZW50OmEyNjRjMTVkLThjM2QtNGY0Yi1hNDNkLWEzYzMzZjgxZGY0MQ==,aws-sesQ29tcG9uZW50OjRmNTM5MWVkLWE3ZDEtNDljZi1hNjViLTE4ZGNmMTRmNGJlMA==,aws-snsQ29tcG9uZW50OmQ0YjhmOTllLWU3YTYtNDUxMS04YWIxLWNkOGQ1M2QyNDJiZg==,aws-sqs
#
Using the Prismatic CLI in Bash ScriptsMultiple prism
commands can be strung together to manage prismatic resources.
For example, to create an instance you need to know the ID of the integration, and the ID of the customer you want to deploy an instance to.
You can use customers:list
, integrations:list
and instances:create
commands together to create a new instance.
# Get the Customer IDCUSTOMER_ID=$( prism customers:list \ --columns id \ --filter 'Name=^FTL Rockets$' \ --no-header)
# Get the Integration IDINTEGRATION_ID=$( prism integrations:list \ --columns id \ --filter 'name=^Acme$' \ --no-header)
# Get the integration's latest version IDVERSION_ID=$( prism integrations:versions ${INTEGRATION_ID} \ --columns id \ --latest-available \ --no-header)
# Create the instanceprism instances:create \ --customer ${CUSTOMER_ID} \ --integration ${VERSION_ID} \ --name 'Acme ERP' \ --description 'Sync data with Acme ERP'
#
Headless prism Usage for CI/CD PipelinesIf you would like to use prism
on a headless (no GUI) server for CI/CD or scripting purposes, you will need to log in on a system that has a web browser and then transfer your "refresh token" to the headless system.
Refresh tokens do not expire, and are used to generate short-lived access tokens for Prismatic's API.
After logging in to prism
with prism login
, get your refresh token with prism me:token --type refresh
.
Take note of your token, and the API endpoint that you are currently using (see that with prism me
).
Now, on our headless CI/CD system, set an environment variable PRISM_REFRESH_TOKEN
with the value you found.
If you use
export PRISM_REFRESH_TOKEN=my-refresh-token
If you're working with regions other than the default US commercial region, you can also specify an endpoint:
export PRISM_REFRESH_TOKEN=my-refresh-tokenexport PRISMATIC_URL=https://app.eu-west-1.prismatic.io
If your app uses a white-labeled domain (like integrations.my-company.com), you can use that endpoint instead for PRISMATIC_URL
.
#
Troubleshooting Common ProblemsMisconfiguration of WSL or NodeJS can result in odd behaviors for a Node-based package like prism
.
Here are a couple of common problems with their respective solutions:
#
Error: spawn cmd.exe ENOENTWhen you run prism login
from within Windows Subsystem for Linux (WSL), you might see Error: spawn cmd.exe ENOENT
.
This is a problem with the WSL distribution's PATH
environment variable.
Ensure that your PATH
environment variable contains System32
, which is where cmd.exe
is located.
Usually, you can run something like this:
export PATH=$PATH:/mnt/c/Windows/System32
#
Error: spawn xdg-open ENOENTIf you run prism login
in a headless Linux environment (a Linux environment without a desktop or web browser such as an Ubuntu server or docker container), prism
will be unable to open a GUI web browser to authenticate you.
You might see an error that reads Error: spawn xdg-open ENOENT
or Error: Exited with code 3
.
You will need to authenticate on a computer with a desktop environment and web browser, and set the refresh token you receive as an environment variable on the headless server. See Headless prism Usage for CI/CD Pipelines.
#
prism: command not foundIf you have followed the instructions above to install prism
, but then see prism: command not found
on Linux or MacOS, or 'prism' is not recognized as an internal or external command, operable program or batch file
on Windows when you run prism
, you likely don't have your NodeJS PATH
configured correctly.
Ensure that your PATH
environment variable contains the bin/
directory of your NodeJS installation.