Skip to content
  • There are no suggestions because the search field is empty.

Getting Started with Opscompass Command Line Interface

Opscompass CLI is a downloadable NPM package that can help you integrate drift & compliance monitoring into your ops workflows.

Installing the Opscompass Command Line Interface (CLI)

The Opscompass Command Line Interface (the CLI) lets you interact with Opscompass directly from your shell.The Opscompass CLI is written in Node.js, which is a free, open-source, cross-platform JavaScript runtime environment.   Node.js requires these components:

  • NVM (Node Version Manager) – used to install and manage Node.js itself
  • js – the actual Node.js package
  • NPM (Node Package Manager) – used to install packages, such as the Opscompass CLI, which are written in Node.js. It is installed by default when Node.js is installed

Operating system prerequisites

The Opscompass CLI runs on most current Linux distributions, see this article for a list of supported versions. The Opscompass CLI is installed as a regular Linux user and does not need root access.

Before installing, your operating system must have these packages installed:

gcc – the GNU C compiler

g++ - the GNU c++ compiler

make - tool that automates the process of building and managing code modules

 

Install NVM

NVM is obtained from the official NVM GitHub repository. Installation instructions are found here: https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating

The command you will use to install NVM is similar to:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Copy the actual command shown on the NVM GitLab page to get the most current version. Once you install NVM, log out and log back in to set up the environment variables.

Verify that NVM in installed by checking the version:

nvm –v

This will output a single line with the NVM version, verifying that it is properly installed

 

Install Node.js (which also installs NPM)

Install the latest Long Term Support version of Node.js, which will also install NPM:

nvm install --lts

Check the version of Node.js and NPM to verify they are installed and working:

node –v

npm -v

Each will return a single line with the installed version of each, verifying that they are properly installed.

 

Install the Opscompass CLI

Use the following command to install the Opscompass CLI using NPM:

npm install -g @opscompass/opscompass-cli

From the command line, type “opscompass” to see the Opscompass CLI help screen, which verifies that the CLI is properly installed

opscompass(optional) Open specific firewall access

The Opscompass CLI NPM package needs to reach out to several Opscompass URLs, if you only want to allow these URLs in your firewall, this article details which URLs to allow.

Login

Login supports the two basic "native app" authentication flows:

  1. Authorization Code with PKCE, the "no-secret" authorization code flow, for clients with interactive browsers
  2. Device authorization flow, for clients without interactive browsers

Authorization Code with PKCE

The most common flow is when you're running the CLI on a host with a web browser. Most Windows and Mac users will be in this situation.

When you run “opscompass login”, the CLI generates some short-lived secrets that are used to make sure only the CLI receives your authentication token. The CLI also starts listening for local HTTP traffic on port 8400 to receive the authorization code from the login page.

The CLI will try to launch the system default browser asking you to log in to Opscompass. Log in using the same credentials you use when logging into the Opscompass web experience. If you haven't authorized the CLI before, after you log in and provide your MFA token, you'll be asked to authorize the CLI application.

Once you've logged in and authorized the CLI, the browser will redirect you to the local HTTP server hosted by the CLI. The CLI will take the authorization code and redeem it with the short-lived secrets to get the Opscompass access token. If it's successful, the browser shows a "Logging in..." page. If anything fails, you'll see "Problems logging in" page. It stops listening for HTTP traffic at this point.

 

Device Authorization

For scenarios where a browser is unavailable, where the CLI can't listen for HTTP traffic, or where the CLI isn't able to launch a browser, you can use the Device Authorization flow.

To use Device Authorization, run ”opscompass login --use-device-code”

opscompass login --use-device-code

The CLI will request a code from the login system and output a URL for you to visit.

  1. The Opscompass CLI makes an API call to the login system to get a device code, which includes a short "public" code (like ABCD-EFGH) and a longer "private" code.
  2. You use the printed URL and code to log in and authorize your device.
  3. The CLI starts polling using the "private" code to see if you have completed the authorization process.

Once you log in and authorize the device, the next time the CLI polls with the "private" code, the CLI receives your Opscompass access token and prints that you're logged in.

If you don't authorize the device or wait too long to complete the process, the CLI will print a warning that the process wasn't successful.

Access Token Usage

Once the CLI receives an access token, it will include that on all calls for resources as long as it remains valid. The CLI is also issued a refresh token, which is redeemed once the access token expires for a fresh access token.

Refresh tokens do expire if you don't use the CLI regularly. Also, even with regular use, we occasionally require you to log in again.

For more information on how long access tokens last, read more in this article.

Re-Authenticating

You can authenticate with

opscompass login

or

opscompass login --use-device-code

as often as you like. Each successful login attempt replaces the stored credentials with the new ones; however, failed login attempts do not remove credentials.

Using the CLI

The CLI is organized into sections called "modules." Each module exposes one or more "commands" that perform the corresponding action. Typically, modules cover a section of Opscompass (resources, accounts, compliance) and commands are the actions for that section (listing, getting, getting details).

Full CLI commands generally take the form:

opscompass module command --parameter1 value --parameter2 value

# examples:

# opscompass resources get --company my-sample-company --id 12345

The relevant API is called and its output is printed to the standard output as JSON. Errors are logged to the standard error.

If no user token is available, you'll be notified that you need to run the “opscompass login” command again.

If an invalid module or command is given, the available modules or commands for that module are listed.

If the required parameters are not provided for a command, you'll be notified of which parameters are missing.

Getting a List of Companies

A simple way to verify that your login is working is to get a list of all companies associated with your user:

opscompass accounts list-companies

Getting Details of a Resource

You'll need a couple pieces of information to get the details of a single resource using the CLI. You'll need the company the resource is associated with and an identifier for the resource.

Company ID

If you want to get details of a resource, you'll need to know your company's ID in Opscompass. You can get this by logging into Opscompass. Your company will be in the URL.

For instance, if you're viewing the Inventory page, your URL will be:

https://app.opscompass.com/your_company_id/inventory

Here, the company id is your_company_id.

Resource ID

You'll also need to provide the ID of the resource you're trying to access. You can get this in two ways: from the cloud and from Opscompass.

Each cloud has a different way to uniquely identify resources. For instance, Azure uses "Resource ID" and AWS uses "ARN".

When you have the cloud's ID for a resource, provide that with "--resource-id".

opscompass resources get --company your_company_id --resource-id "/subscriptions/abcdef00-0000-4000-a000-123456781234/resourceGroups/A-Resource-Group/providers/Microsoft.Web/sites/yoursite"

When you load a resource's details in the Opscompass web experience, you'll see the resource's "Opscompass ID" at the end of the URL. As we add more capabilities to search your resources using the CLI, this ID will be available through command output.

https://app.opscompass.com/your_company_id/inventory/1234567

Here, the Opscompass ID of the resource is 1234567. When you have the Opscompass ID for a resource, provide it with "--id"

opscompass resources get --company your_company_id --id 1234567