@opscompass/opscompass-cli

OpsCompass Command Line Interface

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

[[TOC]]

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 users use this flow.

Start this flow by running 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. 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 expire if you don't use the CLI regularly. Also, even with regular use, we occasionally require you to log in again.

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.

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