How to use Kosli? #

CLI #

In order to record environments, artifacts and evidence to Kosli you need to use the Kosli CLI. The CLI can also be used to search Kosli and find out all you need to know about your runtime environments and artifacts.

Our CLI is an open source and is available for a number of different platforms.

Installing the Kosli CLI #

Kosli CLI can be installed from package managers, by Curling pre-built binaries, or can be used from the distributed Docker images.

Homebrew

If you have Homebrew (available on MacOS, Linux or Windows Subsystem for Linux), you can install the Kosli CLI by running:

brew install kosli-dev/tap/kosli

APT

On Ubuntu or Debian Linux, you can use APT to install the Kosli CLI by running:

sudo sh -c 'echo "deb [trusted=yes] https://apt.fury.io/kosli/ /"  > /etc/apt/sources.list.d/fury.list'
# On a clean debian container/machine, you need ca-certificates
sudo apt install ca-certificates
sudo apt update
sudo apt install kosli

YUM

On RedHat Linux, you can use YUM to install the Kosli CLI by running:

cat <<EOT >> /etc/yum.repos.d/kosli.repo
[kosli]
name=Kosli public Repo
baseurl=https://yum.fury.io/kosli/
enabled=1
gpgcheck=0
EOT

If you get mirrorlist errors (likely if you are on a clean centos container):

cd /etc/yum.repos.d/
sed -i 's/mirrorlist/#mirrorlist/g' /etc/yum.repos.d/CentOS-*
sed -i 's|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g' /etc/yum.repos.d/CentOS-*

yum update -y
yum install kosli

Curl

You can download the Kosli CLI from GitHub.
Make sure to choose the correct tar file for your system.
For example, on Mac with AMD:

curl -L https://github.com/kosli-dev/cli/releases/download/v2.0.0-rc1/kosli_2.0.0-rc1_darwin_amd64.tar.gz | tar zx
sudo mv kosli /usr/local/bin/kosli

Docker

You can run the Kosli CLI in this docker container:

docker run -it --rm ghcr.io/kosli-dev/cli:v2.0.0-rc1 bash

From source

You can build Kosli CLI from source by running:

git clone git@github.com:kosli-dev/cli.git
cd cli
make build

Verifying the installation worked #

Run this command:

kosli version

The expected output should be similar to this:

version.BuildInfo{Version:"v2.0.0-rc1", GitCommit:"4058e8932ec093c28f553177e41c906940114866", GitTreeState:"clean", GoVersion:"go1.19.5"}

Usage #

The Reference section contains all the information you may need to run the Kosli CLI.

Most of the commands require a number of flags. Some of them are required, others are optional and some are conditional - you need to use them if certain conditions occur. Each command doc/help provides details about its flag usage.

Depending on the CI tool you are using, some of the flags (including required ones) may be defaulted, depending on the environment variables provided by the tool. If the flag is defaulted in your CI you don't have to provide it in the command. Here you can find more details about flags defaulted depending on CI.

Environment variables #

Each flag can be provided directly or represented with an environment variable. In order to represent a flag with environment variable you need to create a variable with a KOSLI_ prefix, followed by the flag name, with all letters capitalized and internal dashes replaced by underscores, e.g.:

--api-token is represented by KOSLI_API_TOKEN
--org is represented by KOSLI_ORG

Getting your Kosli API token #

Go to https://app.kosli.com

Log in or sign up using your github account

Open your Profile page (click on your avatar in the top right corner of the page).

Config file #

A config file is an alternative for using Kosli flags or environment variables. Usually you'd use a config file for the values that rarely change - like api token or org, but you can represent all Kosli flags with config file. The key for each value is the same as the flag name, capitalized, so --api-token would become API-TOKEN, and --org would become ORG, etc.

You can use JSON, YAML or TOML format for your config file.

If you want to keep certain Kosli configuration in a file use --config-file flag when running Kosli commands to let the CLI tool know where to look for the file. The file needs a valid format and extension, e.g.:

kosli-conf.json:

{
  "ORG": "my-org",
  "API-TOKEN": "123456abcdef"
}

kosli-conf.yaml:

ORG: "my-org"
API-TOKEN: "123456abcdef"

kosli-conf.toml:

ORG = "my-org"
API-TOKEN = "123456abcdef"

When calling a Kosli CLI command you can skip file extension. For example, to list environments with org and api-token in the configuration file you would run:

$ kosli environment ls --config-file kosli-conf

--config-file defaults to kosli, so if you name your file kosli.<yaml|toml|json> and the file is in the same location as where you run Kosli CLI commands from, you can skip the --config-file altogether.

Dry run #

You can use dry run flag to disable reporting to app.kosli.com - e.g. if you're just trying things out, or troubleshooting (dry run will print the payload the CLI would send in a non dry run mode).

Here are two ways of enabling a dry run:

use the --dry-run flag (no value needed) to enable it per command;
set the KOSLI_DRY_RUN environment variable to TRUE to enable it globally (e.g. in your terminal or CI).

Web UI #

app.kosli.com is an easy way to monitor the status of your environments and flows. All you need to log in is a GitHub account.

app.kosli.com

On the left of the page you can see the menu where you can:

Switch to another organization using dropdown menu
Switch to the Environments or the Flows view
Enter organization settings page

In the top right corner of the page you will see your GitHub avatar where you can access your profile settings (containing your Kosli API key). You'll also find there a link to the page where you can create a shared organization and links to cyber-dojo demo project and to log out.