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

JSONata true Transform incoming data into a new form using JSONata

Dropbox true Interact with the Dropbox API

QuickBooks true Interact with Intuit QuickBooks' Accounting and Payments APIs

Code true Author and run your own 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== jsonata JSONata 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 QuickBooks' Accounting and Payments APIs

Q29tcG9uZW50OjFhOTkwN2E3LWY1NTItNGRiMS04ODJkLWI5MmQ1NTQ5Y2E5OQ== code Code true Author and run your own 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==

jsonata JSONata 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==,jsonata

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'