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# ORyarn 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 meName: Alex CooperEmail: alexander.cooper@progix.ioOrganization: Progix Software

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.

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 --helpBuild, deploy, and support integrations in Prismatic from the comfort of your command line
VERSION  @prismatic-io/prism/1.0.9 darwin-x64 node-v14.15.5
USAGE  $ prism [COMMAND]
COMMANDS  alerts                 Manage Alerting resources  authorization-methods  List Authorization Methods that Components can use  components             Manage, create, and publish Components  customers              Manage Customers  help                   Display this help or command specific help  instances              Manage Instances  integrations           Manage and import Integrations  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           Manage your Organization

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 --helpManage Customers
USAGE  $ prism customers:COMMAND
COMMANDS  customers:create       Create a new Customer  customers:credentials  Manage Customer Credentials  customers:delete       Delete a Customer  customers:list         List your Customers  customers:update       Update a Customer  customers:users        Manage Customer Users

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 --helpCreate 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:listLabel              Public DescriptionAWS S3             true   Interact with AWS S3 objects and bucketsHTTP               true   Make HTTP requests to URLs such as REST APIs, Webhooks, etc.SFTP               true   Read and write files or directories to/from SFTP serversSlack              true   Post messages to SlackJSONata            true   Transform incoming data into a new form using JSONataDropbox            true   Interact with the Dropbox APIQuickBooks         true   Interact with Intuit QuickBooks' Accounting and Payments APIsCode               true   Author and run your own codeChange 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 --extendedId                                                               Key        Label              Public DescriptionQ29tcG9uZW50OjJlMDcyMGU4LTFjNTUtNDY1Ni04NzY0LTI1N2RmZDVhNTE3Mw== aws-s3     AWS S3             true   Interact with AWS S3 objects and bucketsQ29tcG9uZW50OmY0NjUyMjg5LTU1MDMtNGYzZi1iYjU1LWVlNDA4MjhjYTFlMQ== 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 serversQ29tcG9uZW50OjlhNDcyNDRiLTNhNTgtNDM0ZC1hZmZmLWIxMjZjNWY2NDA1NQ== slack      Slack              true   Post messages to SlackQ29tcG9uZW50OjkwYWE4NjhiLWRmMDQtNDliMS04M2RiLTM1NGU3Njk2NTFkOA== jsonata    JSONata            true   Transform incoming data into a new form using JSONataQ29tcG9uZW50OjViYzBlMWE5LWI2ZjAtNDE5YS04NTQxLTg4NGMxNjJmNzMxZQ== dropbox    Dropbox            true   Interact with the Dropbox APIQ29tcG9uZW50Ojk5MThhOTdjLTgxMTMtNGMyMi1iOTY3LWU3OWFlODlhZGRhYg== quickbooks QuickBooks         true   Interact with Intuit QuickBooks' Accounting and Payments APIsQ29tcG9uZW50OjFhOTkwN2E3LWY1NTItNGRiMS04ODJkLWI5MmQ1NTQ5Y2E5OQ== code       Code               true   Author and run your own codeQ29tcG9uZW50OjQyODdiOGJkLTAxMzMtNDMxNy04NmMzLTdkZmJlYzM2MjQ2Mw== 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,idKey        Label              Idaws-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 DescriptionAWS 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,keyId,KeyQ29tcG9uZW50OjJlMDcyMGU4LTFjNTUtNDY1Ni04NzY0LTI1N2RmZDVhNTE3Mw==,aws-s3Q29tcG9uZW50OmY0NjUyMjg5LTU1MDMtNGYzZi1iYjU1LWVlNDA4MjhjYTFlMQ==,httpQ29tcG9uZW50OmEwNDFmMTBmLWVkMTAtNDBkNy1hYmMzLTQyMzA1ZDlkYTExMA==,sftpQ29tcG9uZW50OjlhNDcyNDRiLTNhNTgtNDM0ZC1hZmZmLWIxMjZjNWY2NDA1NQ==,slackQ29tcG9uZW50OjkwYWE4NjhiLWRmMDQtNDliMS04M2RiLTM1NGU3Njk2NTFkOA==,jsonataQ29tcG9uZW50OjViYzBlMWE5LWI2ZjAtNDE5YS04NTQxLTg4NGMxNjJmNzMxZQ==,dropboxQ29tcG9uZW50Ojk5MThhOTdjLTgxMTMtNGMyMi1iOTY3LWU3OWFlODlhZGRhYg==,quickbooksQ29tcG9uZW50OjFhOTkwN2E3LWY1NTItNGRiMS04ODJkLWI5MmQ1NTQ5Y2E5OQ==,codeQ29tcG9uZW50OjQyODdiOGJkLTAxMzMtNDMxNy04NmMzLTdkZmJlYzM2MjQ2Mw==,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 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=Fabricate 3D Model' \    --no-header)
# Create the instanceprism 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'

Troubleshooting Common Problems#

Misconfiguration 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 ENOENT#

When 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 ENOENT#

If 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 copy over the cached API tokens to your headless Linux environment. Your cached API key is available in $HOME/.config/prism/config.yml and it will look something like this:

accessToken: >-  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL3ByaXNtYXRpYy5pby9lb...expiresIn: 86400refreshToken: AKES5555555551zpAKJcA19Kx5O9AKc90-1zpAKJcA19Kscope: openid profile email offline_accesstokenType: Bearer

Copy this file to your headless Linux system at $HOME/.config/prism/config.yml.

prism: command not found#

If 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.