CLI
Interact with the OpsLevel API via our CLI to perform CRUD actions on services, teams, or checks and even submit deploy events.
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
Updated 7 months ago