Skip to content

Getting Started with the Contrail CLI

Installation

  1. The Contrail CLI requires Node.js v20. Please download it from nodejs.org and install it on your machine.
  2. Install the Contrail CLI using npm: @contrail/cli 
    npm install -g @contrail/cli

Setting Your Org Slug

To target a specific VibeIQ environment, or "org", you must specify the slug for the org you would like to work in. This can be done by setting the CONTRAIL_CLI_ORG_SLUG environment variable or by using the contrail config command.

Use a CLI command to set your org slug without an environment variable
contrail config set --orgSlug=yourOrgSlug
Store your org slug as an environment variable
export CONTRAIL_CLI_ORG_SLUG="myOrgSlug"
Store your org slug as an environment variable
set CONTRAIL_CLI_ORG_SLUG=myOrgSlug
Store your org slug as an environment variable
$env:CONTRAIL_CLI_ORG_SLUG="myOrgSlug"

Authentication

Authenticating with Email and Password

If you are using SSO, you will not have a VibeIQ password. Please see Authentication for SSO Users for instructions on how to authenticate to the CLI.

If you are not using SSO, you can authenticate to the CLI using the same email and password used to log in to the VibeIQ platform. The CLI will prompt you for an email and password for each command you run that requires authentication. For convenience, you may store your email and password in environment variables so that the CLI can use them for every command.

Email is case-sensitive

Please ensure you use the same casing for your email address when authenticating to the CLI as you use when logging in to the VibeIQ platform. This is an exact match. Please reference the Users section of the Admin Console to see the exact email address used to create your account.

Store your email and password as environment variables for convenience
export CONTRAIL_CLI_EMAIL="me@example.com"
export CONTRAIL_CLI_PASSWORD="yourSecretPassword"
Store your email and password as environment variables for convenience
set CONTRAIL_CLI_EMAIL=me@example.com
set CONTRAIL_CLI_PASSWORD=yourSecretPassword
Store your email and password as environment variables for convenience
$env:CONTRAIL_CLI_EMAIL="me@example.com"
$env:CONTRAIL_CLI_PASSWORD="yourSecretPassword"

Authentication for SSO Users

If your organization uses SSO for login, will not have a VibeIQ password, and thus cannot authenticate to the CLI using one. You may either authenticate using an App API key, or use the vibeAccessToken stored in your browser cookies.

To retrieve a vibeAccessToken, you can use the following steps:

  1. Open the VibeIQ platform in your browser.
  2. Open the developer tools in your browser (usually by right-clicking on the page and selecting "Inspect" or "Inspect Element").
  3. Go to the Application tab (Chrome) or Storage tab (Safari).
  4. In the left sidebar, find and click on "Cookies".
  5. Find the cookie named vibeAccessToken underneath any *.vibeiq.com domains and copy its value.

Once you have retrieved either an App API key or vibeAccessToken, set it to CONTRAIL_CLI_API_KEY as an environment variable .

Store your API key as an environment variable
export CONTRAIL_CLI_API_KEY="yourVibeAccessTokenOrAppApiKey"
Store your API key as an environment variable
set CONTRAIL_CLI_API_KEY=yourVibeAccessTokenOrAppApiKey
Store your API key as an environment variable
$env:CONTRAIL_CLI_API_KEY="yourVibeAccessTokenOrAppApiKey"

Authentication with App API Keys

Assuming you already have access to authenticate with another pattern, like email and password, you may retrieve an App's API key and use it to authenticate. To do so, you can retrieve an App's API key with the below command. After generating this key, if you begin using it as your authentication pattern, all actions performed by your CLI commands will register as actions taken by that app.

Retreive an App's API key. This will prompt you to select the app of which to get the key for.
contrail app getApiKey

Once you have an app API key, you can use it in your automation scripts by setting it as the CONTRAIL_CLI_API_KEY environment variable.

Use the API key to authenticate when running CLI commands
export CONTRAIL_CLI_API_KEY="MY_SECRET_KEY"
Use the API key to authenticate when running CLI commands
set CONTRAIL_CLI_API_KEY=MY_SECRET_KEY
Use the API key to authenticate when running CLI commands
$env:CONTRAIL_CLI_API_KEY="MY_SECRET_KEY"

Storing authentication credentials in a configuration file

You can store authentication credentials in a configuration file by following these steps:

1. Create a Configuration File

Use the following command to create an empty configuration file for your organization. Replace ORG_SLUG with your organization's slug.

contrail config create --name=ORG_SLUG

2. Use the Configuration File

Set the created configuration file as the current one. This will ensure that all subsequent commands will use this configuration file.

contrail config use ORG_SLUG

3. Store Credentials in the Configuration File

Run a command that requires authentication, such as contrail app getApiKey. This will prompt you for your credentials, which will then be stored in the configuration file.

contrail app getApiKey

The configuration file will be stored at the following location:

/Users/apple/.vibeiq/configs/ORG_SLUG.json

C:\Users\YourUsername\.vibeiq\configs\ORG_SLUG.json

By following these steps, you can securely store your authentication credentials in a configuration file and use them for subsequent CLI commands.

Using Contrail CLI for Automation

The Contrail CLI enables organizations to automate common tasks like exporting and backing up configurations or publishing and deploying new versions of your app. This guide provides a step-by-step explanation of how to automate the usage of the Contrail CLI with CI/CD tools like GitHub Actions.

The following sample GitHub Actions workflow automates the process of using the Contrail CLI to export organizational configuration and commits changes to the main branch if any updates are detected.

Workflow Breakdown

1. Workflow Dispatch

The workflow is triggered manually through the workflow_dispatch event.

2. Job Setup: useContrailCli

This job, useContrailCli, runs on an ubuntu-24.04 environment and follows these steps:

  • Install Node.js: Sets up Node.js to support the Contrail CLI.
  • Install contrail-cli: Installs the Contrail CLI globally using npm.
jobs:
  useContrailCli:
    runs-on: ubuntu-24.04
    steps:
      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install contrail-cli
        run: npm install -g @contrail/cli

3. Repository Setup

This section involves setting up the repository by following these steps:

  • Checkout Repository: Checks out the repository’s main branch.
  • Create a New Branch: Generates a unique branch ID for tracking changes and creates a new branch based on the main branch.
- name: Checkout the repo
  uses: actions/checkout@v4
  with:
    ref: main

- name: Create a new branch
  run: |
    NEW_BRANCH_ID=$(uuidgen)
    NEW_BRANCH_NAME="zts-wf-test${NEW_BRANCH_ID}"
    git checkout -b "$NEW_BRANCH_NAME"

4. Export Configuration Using Contrail CLI

This section details the process for exporting configuration data using the Contrail CLI:

  • Export Org Config: Runs the Contrail CLI to export configuration data.

Note: You can use CONTRAIL_CLI_API_KEY or CONTRAIL_CLI_EMAIL and CONTRAIL_CLI_PASSWORD.

- name: Export the org config
  run: |
    cd ./history/config
    spawn contrail instance export -f
  env:
    CONTRAIL_CLI_EMAIL: ${{ secrets.CONTRAIL_CLI_EMAIL }}
    CONTRAIL_CLI_PASSWORD: ${{ secrets.CONTRAIL_CLI_PASSWORD }}
    CONTRAIL_CLI_ORG_SLUG: ${{ secrets.CONTRAIL_CLI_ORG_SLUG }}
    CONTRAIL_CLI_API_KEY: ${{ secrets.CONTRAIL_CLI_API_KEY }}

Security Considerations

This section outlines the security measures taken in the workflow:

  • Use of GitHub Secrets: The workflow utilizes GitHub Secrets (CONTRAIL_CLI_EMAIL, CONTRAIL_CLI_PASSWORD, CONTRAIL_CLI_ORG_SLUG, and CONTRAIL_CLI_API_KEY) to securely handle credentials. Ensure that these secrets are correctly configured in your repository settings to prevent unauthorized access.

Conclusion

This automation simplifies the process of exporting and versioning organization configuration with the Contrail CLI through GitHub Actions. It provides an efficient, trackable, and CI/CD-friendly workflow.