OpsCompass Integrations
      Back to home
      1. Help Center
      2. OpsCompass Integrations

      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.

      Download the OpsCompass CLI from NPM

      https://www.npmjs.com/package/@opscompass/opscompass-cli

      The OpsCompass Command Line Interface (the CLI) lets you interact with OpsCompass directly from your shell.

      (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 yoru 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 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