Getting Started
      Back to home
      1. Help Center
      2. Opscompass CLI
      3. Getting Started

      Download and Initialization

      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.

      opscompass login

      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.