Prismatic CLI Usage

CLI Tool Overview

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 Tool

Prismatic'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
# OR
yarn global add @prismatic-io/prism

Authenticating with the CLI Tool

Once 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 Cooper
Email: alexander.cooper@progix.io
Organization: Progix Software

If you want to view the authentication token that your CLI tool uses, run prism me:token.

prism me:token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJqaEZORU01TWpBeVFVUkZNRGxCT1RKRE4wSkdSVUk1TmpSQk1VTXdORGd5TWpkRE5FRXpRUSJ9.eyJodHRwczovL3ByaXNtYXRpYy5pby9lbWFpbCI6InByaXNtYXRpYy5pc0Bhd2Vzb21lLnRsZCIsImh0dHBzOi8vcHJpc21hdGljLmlvL2VtYWlsX3ZlcmlmaWVkIjp0cnVlLCJpc3MiOiJodHRwczovL3ByaXNtYXRpYy1pby1kZXYuYXV0aDAuY29tLyIsInN1YiI6ImF1dGgwfDVlNzkyYzA3ZTRmYjg1MGM2NjVlZmVhOSIsImF1ZCI6WyJodHRwczovL3ByaXNtYXRpYy5pby9hcGkiLCJodHRwczovL3ByaXNtYXRpYy1pby1kZXYuYXV0aDAuY29tL3VzZXJpbmZvIl0sImlhdCI6MTU5MTYzMjExNSwiZXhwIjoxNTkxNzE4NTE1LCJhenAiOiJSM3VBMjdMYnhxeWFuR1ZYaktwWGdRbzVBNFRLNDRzNyIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwgb2ZmbGluZV9hY2Nlc3MifQ.gYulreC9ZyPIL3ZeUwSir-Qks6ULxK4QmSkS2BCT7ik

To clear your token from memory and log out, run prism logout.

Running CLI Commands and Getting Help

All 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
VERSION
prism/0.1.0 darwin-x64 node-v12.16.2
USAGE
$ prism [COMMAND]
COMMANDS
alerts Marks a list of Alert Events as cleared
authorization-methods List Authorization Methods that Components can use
billing List Invoices
components List Actions that Components implement
customers Create a new Customer
help display help for prism
instances Create an Instance
integrations Create an Integration
login Log in to your Prismatic account
logout Log out of your Prismatic account
logs List Log Severities for use by Alert Triggers
me Print your user profile information
organization Create a set of Organization-level Credentials for use by Instance Actions
register Register with Prismatic
triggers List types of triggers that can trigger integrations

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
USAGE
$ prism customers:COMMAND
COMMANDS
customers:create Create a new Customer
customers:credentials Create a set of Customer-specific Credentials for use by Instance Actions
customers:delete Delete a Customer
customers:list List your Customers
customers:update Update a Customer
customers:users Create a User for the specified 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
OPTIONS
-d, --description=description longer description of the customer
-n, --name=name (required) short name of the new customer

Listing Resources

All 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
AWS S3 true Interact with AWS S3 objects and buckets
HTTP true Make HTTP requests to URLs such as REST APIs, Webhooks, etc.
SFTP true Read and write files or directories to/from SFTP servers
Slack true Post messages to Slack
Transform Data true Transform incoming data into a new form using JSONata
Dropbox true Interact with the Dropbox API
QuickBooks true Interact with Intuit QuickBook's Accounting and Payments APIs
Code true Author and run custom code
Change Data Format true Change data format from one format to another

Listing Resource IDs

All 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
Q29tcG9uZW50OjJlMDcyMGU4LTFjNTUtNDY1Ni04NzY0LTI1N2RmZDVhNTE3Mw== aws-s3 AWS S3 true Interact with AWS S3 objects and buckets
Q29tcG9uZW50OmY0NjUyMjg5LTU1MDMtNGYzZi1iYjU1LWVlNDA4MjhjYTFlMQ== http HTTP true Make HTTP requests to URLs such as REST APIs, Webhooks, etc.
Q29tcG9uZW50OmEwNDFmMTBmLWVkMTAtNDBkNy1hYmMzLTQyMzA1ZDlkYTExMA== sftp SFTP true Read and write files or directories to/from SFTP servers
Q29tcG9uZW50OjlhNDcyNDRiLTNhNTgtNDM0ZC1hZmZmLWIxMjZjNWY2NDA1NQ== slack Slack true Post messages to Slack
Q29tcG9uZW50OjkwYWE4NjhiLWRmMDQtNDliMS04M2RiLTM1NGU3Njk2NTFkOA== transform Transform Data true Transform incoming data into a new form using JSONata
Q29tcG9uZW50OjViYzBlMWE5LWI2ZjAtNDE5YS04NTQxLTg4NGMxNjJmNzMxZQ== dropbox Dropbox true Interact with the Dropbox API
Q29tcG9uZW50Ojk5MThhOTdjLTgxMTMtNGMyMi1iOTY3LWU3OWFlODlhZGRhYg== quickbooks QuickBooks true Interact with Intuit QuickBook's Accounting and Payments APIs
Q29tcG9uZW50OjFhOTkwN2E3LWY1NTItNGRiMS04ODJkLWI5MmQ1NTQ5Y2E5OQ== code Code true Author and run custom code
Q29tcG9uZW50OjQyODdiOGJkLTAxMzMtNDMxNy04NmMzLTdkZmJlYzM2MjQ2Mw== reformat Change Data Format true Change data format from one format to another

Configuring Columns of a List to Display

You 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
aws-s3 AWS S3 Q29tcG9uZW50OjJlMDcyMGU4LTFjNTUtNDY1Ni04NzY0LTI1N2RmZDVhNTE3Mw==
http HTTP Q29tcG9uZW50OmY0NjUyMjg5LTU1MDMtNGYzZi1iYjU1LWVlNDA4MjhjYTFlMQ==
sftp SFTP Q29tcG9uZW50OmEwNDFmMTBmLWVkMTAtNDBkNy1hYmMzLTQyMzA1ZDlkYTExMA==
slack Slack Q29tcG9uZW50OjlhNDcyNDRiLTNhNTgtNDM0ZC1hZmZmLWIxMjZjNWY2NDA1NQ==
transform Transform Data Q29tcG9uZW50OjkwYWE4NjhiLWRmMDQtNDliMS04M2RiLTM1NGU3Njk2NTFkOA==
dropbox Dropbox Q29tcG9uZW50OjViYzBlMWE5LWI2ZjAtNDE5YS04NTQxLTg4NGMxNjJmNzMxZQ==
quickbooks QuickBooks Q29tcG9uZW50Ojk5MThhOTdjLTgxMTMtNGMyMi1iOTY3LWU3OWFlODlhZGRhYg==
code Code Q29tcG9uZW50OjFhOTkwN2E3LWY1NTItNGRiMS04ODJkLWI5MmQ1NTQ5Y2E5OQ==
reformat Change Data Format Q29tcG9uZW50OjQyODdiOGJkLTAxMzMtNDMxNy04NmMzLTdkZmJlYzM2MjQ2Mw==

Filtering List Output

You 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
AWS S3 true Interact with AWS S3 objects and buckets

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 Output

Lists 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,Key
Q29tcG9uZW50OjJlMDcyMGU4LTFjNTUtNDY1Ni04NzY0LTI1N2RmZDVhNTE3Mw==,aws-s3
Q29tcG9uZW50OmY0NjUyMjg5LTU1MDMtNGYzZi1iYjU1LWVlNDA4MjhjYTFlMQ==,http
Q29tcG9uZW50OmEwNDFmMTBmLWVkMTAtNDBkNy1hYmMzLTQyMzA1ZDlkYTExMA==,sftp
Q29tcG9uZW50OjlhNDcyNDRiLTNhNTgtNDM0ZC1hZmZmLWIxMjZjNWY2NDA1NQ==,slack
Q29tcG9uZW50OjkwYWE4NjhiLWRmMDQtNDliMS04M2RiLTM1NGU3Njk2NTFkOA==,transform
Q29tcG9uZW50OjViYzBlMWE5LWI2ZjAtNDE5YS04NTQxLTg4NGMxNjJmNzMxZQ==,dropbox
Q29tcG9uZW50Ojk5MThhOTdjLTgxMTMtNGMyMi1iOTY3LWU3OWFlODlhZGRhYg==,quickbooks
Q29tcG9uZW50OjFhOTkwN2E3LWY1NTItNGRiMS04ODJkLWI5MmQ1NTQ5Y2E5OQ==,code
Q29tcG9uZW50OjQyODdiOGJkLTAxMzMtNDMxNy04NmMzLTdkZmJlYzM2MjQ2Mw==,reformat

Using the Prismatic CLI in Bash Scripts

Multiple prism commands can be strung together to manage prismatic resources. For example, to create an instance of an integration 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 ID
CUSTOMER_ID=$(
prism customers:list \
--columns id \
--filter 'name=FTL Rockets' \
--no-header)
# Get the Integration ID
INTEGRATION_ID=$(
prism integrations:list \
--columns id \
--filter 'name=Fabricate 3D Model' \
--no-header)
# Create the instance
prism instances:create \
--customer ${CUSTOMER_ID} \
--integration ${INTEGRATION_ID} \
--name 'Fabricate 3D Model for FTL Rockets' \
--description 'Queue the 3D printing job for a model rocket'
Last updated on