CLI

With the OpsLevel CLI you can perform create, retrieve, update and delete actions on the data in OpsLevel.

Pre-Requisites

You will need an API Token to authorize the CLI to talk to your account via an environment variable

export OPSLEVEL_API_TOKEN=XXX

Installation

Homebrew

brew install opslevel/tap/cli

Other OS

Please visit our Github releases page and download the binary for your operating system.

Introduction

The CLI is setup with a few top level “action” commands like get, list, create, delete which have subcommands for each “resource object” in OpsLevel. So most commands will take the format of opslevel <action> <resource> with a handful of exceptions.

It should also be noted that the CLI is currently in beta and does not yet support all resources and CRUD actions.

Retrieve Data

One of the main use-cases is to retrieve information about your account so you can use your service catalog to power other tools or processes.

First let’s start with listing the all tier and lifecycle objects in your account.

> opslevel list tier 
Alias   ID
tier_1  Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTg
tier_2  Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUx
tier_3  Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUy
tier_4  Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUz
> opslevel list lifecycle
Alias                ID
pre-alpha            Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMjI
alpha                Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMjM
beta                 Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMjU
generally_available  Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMjY
end-of-life          Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMjg

The output is the valid alias and id values for each tier and lifecycle that you may need to use in other commands.

Lets inspect one of the level objects. Use the corresponding list action then select the id for one of them and then feed it to a get action.

> opslevel list level         
Alias     ID                                
beginner  Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTg   
bronze    Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUx  
silver    Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUy  
gold      Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUz  
> opslevel get level Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUy
{
  "Alias": "silver",
  "description": "Services in this level satisfy important and critical checks. This is considered healthy.",
  "id": "Z2lkOi8vb3BzbGV2ZWwvTGV2ZWwvMTUy",
  "Index": 2,
  "Name": "Silver"
}

An additional feature of the list command is to use the output flag \-o json to convert the output to be machine readable

> opslevel list lifecycle -o json
[
    {
        "Alias": "pre-alpha",
        "Description": "Service is only being used/tested by the people building it.",
        "Id": "Z2lkOi8vb3BzbGV2ZWwvTGlmZWN5Y2xlLzQyNg",
        "Index": 1,
        "Name": "Pre-alpha"
    },
    {
        "Alias": "alpha",
        "Description": "Service is supporting features used by others at the company, or a very small set of friendly customers.",
        "Id": "Z2lkOi8vb3BzbGV2ZWwvTGlmZWN5Y2xlLzQyNw",
        "Index": 2,
        "Name": "Alpha"
    },
    ... More Data ...

Pair this with jq and you have a very powerful combo to slice and dice the data in opslevel for other purposes

> opslevel list lifecycle -o json | jq 'map({"key": .Alias, "value": .Index}) | from_entries'
{
  "pre-alpha": 1,
  "alpha": 2,
  "beta": 3,
  "generally_available": 4,
  "end-of-life": 5
}

Create Data

To create simple objects in OpsLevel you can use the create action subcommands. Here is an example showing how to create a new rubric category which returns the id of the newly created resource.

> opslevel create category Chaos
Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMTE4OA
> opslevel get category Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMTE4OA
{
  "id": "Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMTE4OA",
  "Name": "Chaos"
}

Some resources in OpsLevel will need more complex data structures when creating them and in these cases the data can be supplied by a yaml file on disk or from stdin.

cat << EOF | opslevel create check -f -
version: 1
kind: generic
spec:
    message: |-
        
          ### Check failed
          Service **** has an incident in the last 7 days:  last incident was 
        
    name: 'PagerDuty: No incidents in the last 7 days'
    notes: ""
    serviceSelector: .services[] | .name
    successCondition: .services[]  | .last_incident_timestamp == null or (.last_incident_timestamp | fromdate < now - 7*24*3600)
EOF

Delete data

The delete action allows you to pass the id of a resource to delete. Lets delete the category we just created.

> opslevel delete category Z2lkOi8vb3BzbGV2ZWwvQ2F0ZWdvcnkvMTE4OA

This command paired with the list command paired with jq and xargs creates a really easy way to cleanup a bunch of resources in OpsLevel.

> opslevel list checks -o json | jq -r '.[] | .Id' | xargs -n 1 opslevel delete check
deleted 'Z2lkOi8vb3BzbGV2ZWwvQ2hlY2tzOjpHZW5lcmljLzQ1MTQ' check
deleted 'Z2lkOi8vb3BzbGV2ZWwvQ2hlY2tzOjpHZW5lcmljLzQ1MTc' check
deleted 'Z2lkOi8vb3BzbGV2ZWwvQ2hlY2tzOjpHZW5lcmljLzQ1MTM' check
deleted 'Z2lkOi8vb3BzbGV2ZWwvQ2hlY2tzOjpHZW5lcmljLzQ1MTU' check

Special commands

There are also some specialized commands included with the CLI that provide specific needs such as the export or completion commands. You can always introspect aspects about the CLI by adding the \-h to print out help information or to see the available commands.

You can use the completion command to generate the autocompletion script for the specified shell to help with tab completion of the commands.

There is also an export terraform command which you can read more about in our Terraform docs

Deploys

You can create a deploy event using the CLI.

opslevel create deploy -i "https://app.opslevel.com/integrations/deploy/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx" -s "shopping_cart"

or with additional details - you can read more about the available fields in our deploy documentation

cat << EOF | opslevel create deploy -i "https://app.opslevel.com/integrations/deploy/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx"
service: "shopping_cart"
description: "Deployed by CI Pipeline: Deploy #234"
environment: "Production"
deploy-number: 234
deploy-url: https://heroku.deploys.com
dedup-id: 9ae54794-dfc5-4ac8-b1b5-78789f20f3f8
deployer:
  id: 1a9f841f-9a3d-4423-a05a-7e9c31a02b16
  name: Michael Scott
  email: [email protected]
EOF

It should be noted that the CLI will auto gather fields where it can such as deployed-at with the current time of when the command is run or all of the commit information from the git repository if run inside a directory with the .git folder.

FAQs

What commands, options, and additional arguments are supported in the CLI?

The opslevel-cli's help menu is well documented and includes examples. Add the -h or --help at end of the opslevel command to get started.

Running opslevel -h will show the following:

% opslevel -h
Opslevel Commandline Tool

Usage:
  opslevel [command]

Available Commands:
  assign      Assign properties to resources
  completion  Generate the autocompletion script for the specified shell
  create      Create resources or events from a file or stdin
  delete      Delete or remove data in OpsLevel
  example     Examples of OpsLevel resources
  export      Export OpsLevel data to other tools or services
  get         Get detailed info about resources in OpsLevel
  graphql     Make authenticated raw GraphQL requests
  help        Help about any command
  import      Import data to OpsLevel.
  list        List all resources in OpsLevel
  run         Invoked to execute various OpsLevel functions
  unassign    Unassign properties from resources
  update      Update resources or events from a file or stdin
  version     Print version information