keptn CLI

In this section, the functionality and commands of the keptn CLI are described. The keptn CLI allows installing keptn, configuring keptn, creating new projects, onboarding new services, and sending new artifact events.

If you are unfamiliar with keptn, we recommend to first watch this community meeting recording, which provides an introduction to keptn.


Install the keptn CLI

Every release of keptn provides binaries for the keptn CLI. These binaries are available for Linux, macOS, and Windows.

  1. Download the version matching your operating system
  2. Unpack the download
  3. Find the keptn binary in the unpacked directory.

    • Linux / macOS

      add executable permissions (chmod +x keptn), and move it to the desired destination (e.g. mv keptn /usr/local/bin/keptn)

    • Windows

      move/copy the executable to the desired folder and, optionally, add the executable to your PATH environment variable for a more convenient experience.

  4. Now, you should be able to run the keptn CLI by

    keptn --help
    keptn CLI

Start using the keptn CLI

In the following, the commands provided by the keptn CLI are described. All of these commands provide a help flag (--help), which describes details of the respective command (e.g., usage of the command or description of flags).

Note: In the current version, keptn is missing checks whether the sent command is executed correctly. In order to guarantee the expected behavior, please strictly use the following commands in the specified order. In future releases, we add additional checks whether the executed commands succeeded or failed.

keptn install

The keptn CLI allows to install keptn on a server. Further details are provided here.

keptn install

keptn auth

Before the keptn CLI can be used, it needs to be authenticated against a keptn server. Therefore, an endpoint and an API token are required.

Note: The CLI is automatically authenticated after installing keptn using the CLI. Hence, keptn auth can be skipped.

If the authentication is successful, keptn will inform the user. Furthermore, if the authentication is successful, the endpoint and the API token are stored in a password store of the underlying operating system. More precisely, the keptn CLI stores the endpoint and API token using pass in case of Linux, using Keychain in case of macOS, or Wincred in case of Windows.

Linux / macOS

Set the needed environment variables.

KEPTN_ENDPOINT=https://$(kubectl get ksvc -n keptn control -o=yaml | yq r - status.domain)
KEPTN_API_TOKEN=$(kubectl get secret keptn-api-token -n keptn -o=yaml | yq - r data.keptn-api-token | base64 --decode)

Authenticate to the keptn server.

keptn auth --endpoint=$KEPTN_ENDPOINT --api-token=$KEPTN_API_TOKEN

Note: If you receive a warning Using a file-based storage for the key because the password-store seems to be not set up. it is because a password store could not be found in your environment. In this case, the credentials are stored in a file called .keptn in your home directory.


Please expand the corresponding section matching your CLI tool.


For the Windows PowerShell, a small script is provided that installs the PSYaml module and sets the environment variables. Please note that the PowerShell might have to be started with Run as Administrator privileges to install the module.

  1. Copy the following snippet and paste it in your PowerShell. The snippet will be automatically executed line by line.

    Install-Module PSYaml
    import-module psyaml
    $yamlText = kubectl get secret keptn-api-token -n keptn -o=yaml
    $content = ''
    foreach ($line in $yamlText) { $content = $content + "`n" + $line }
    $yaml = ConvertFrom-YAML $content
    $Env:KEPTN_API_TOKEN = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($"keptn-api-token"))
    $yamlText = kubectl get ksvc -n keptn control -o=yaml
    $content = ''
    foreach ($line in $yamlText) { $content = $content + "`n" + $line }
    $yaml = ConvertFrom-YAML $content
    $ENDPOINT = $yaml.status.domain
    $Env:KEPTN_ENDPOINT = "https://$ENDPOINT"
  2. Now that everything we need is stored in environment variables, we can proceed with authorizing the keptn CLI. To authenticate against the keptn server use command auth and your endpoint and API token:

    keptn.exe auth --endpoint=$Env:KEPTN_ENDPOINT --api-token=$Env:KEPTN_API_TOKEN

Command Line

In the Windows Command Line, a couple of steps are necessary.

  1. Get the keptn API Token encoded in base64

    kubectl get secret keptn-api-token -n keptn -o=yaml
    apiVersion: v1
      keptn-api-token: abcdefghijkladfaea
    kind: Secret
    type: Opaque
  2. Take the encoded API token - it is the value from the key keptn-api-token (in this example, it is abcdefghijkladfaea) and save it in a text file, e.g., keptn-api-token-base64.txt

  3. Decode the file

    certutil -decode keptn-api-token-base64.txt keptn-api-token.txt
  4. Open the newly created file keptn-api-token.txt, copy the value and paste it into the next command

    set KEPTN_API_TOKEN=value-of-your-token
  5. Get the keptn server endpoint

    kubectl get ksvc -n keptn control -o yaml
    kind: Service
        hostname: control.keptn.svc.cluster.local
  6. Copy the domain value and save it in an environment variable

  7. Now that everything we need is stored in environment variables, we can proceed with authorizing the keptn CLI.

    To authenticate against the keptn server use command auth and your endpoint and API token:

    keptn.exe auth --endpoint=%KEPTN_ENDPOINT% --api-token=%KEPTN_API_TOKEN%

keptn configure

In order to work with GitHub (i.e. create a new project, make commits), keptn requires a GitHub organization, the GitHub user, and the GitHub personal access token belonging to that user. Therefore, the keptn CLI is used to set the GitHub organization, the GitHub user, and the GitHub personal access token belonging to that user in the keptn server.

Note: Keptn is automatically configured after installing keptn using the CLI. Hence, keptn configure can be skipped

To configure, use the command configure and specify the GitHub organization (flag --org), user (flag --user), and personal access token (flag --token):

keptn configure --org=gitHubOrg --user=gitHub_keptnUser --token=XYZ

keptn create project

Before onboarding a service, a project needs to be created. A project represents a repository in the GitHub organization that is used by keptn. This project contains branches representing the multi-stage environment (e.g., dev, staging, and production stage). In other words, the separation of stage configurations is based on repository branches. To describe each stage, a shipyard.yaml file is needed that specifies the name, deployment strategy, and test strategy as shown below:

registry: sockshop
  - name: "dev"
    deployment_strategy: "direct"
    test_strategy: "functional"
  - name: "staging"
    deployment_strategy: "blue_green_service"
    test_strategy: "performance"
  - name: "production"
    deployment_strategy: "blue_green_service"

To create a new project, use the command create project and specify the name of the project as well as the shipyard.yaml file.

keptn create project your_project shipyard.yml

keptn onboard service

After creating a project which represents a repository in your GitHub organization, the keptn CLI allows to onboard services into this project. Please note that for describing the Kubernetes resources, Helm charts are used. Therefore, the keptn CLI allows setting a Helm values description in the before created project. Optionally, the user can also provide a Helm deployment and service description.

To onboard a service, use the command onboard service and provide the project name (flag --project), the Helm chart values (flag --values) and optionally also deployment (flag --deployment) and service (flag --service) descriptions.

keptn onboard service --project=your_project --values=values.yaml


keptn onboard service --project=your_project --values=values.yaml --deployment=deployment.yaml --service=service.yaml

To start onboarding a service, please see the Onboarding a Service use case.

keptn send event new-artifact

After onboarding a service, the keptn CLI allows pushing a new artifact for the service. This artifact is a Docker image, which can be located at Docker Hub, Quay, or any other registry storing docker images. The new artifact is pushed in the first stage specified in the shipyard.yaml file (usually this will be the dev-stage). Afterwards, keptn takes care of deploying this new artifact.

To push a new artifact, use the command send event new-artifact, which sends a new-artifact-event to keptn in order to deploy a new artifact for the specified service in the provided project. Therefore, this command takes the project (flag --project), the service (flag --service), as well as the image (flag --image) and tag (flag --tag) of the new artifact.

keptn send event new-artifact --project=your_project --service=your_service --tag=0.7.1

keptn send event

This command allows sending arbitrary keptn events. These events have to follow the Cloud Events specification and are written in JSON. Note: This command is not required for any use case and requires precise keptn event definitions as you can find here.

To send an arbitrary keptn event, use the command send event and pass the file containing the event (flag --file).

keptn send event --file=new_artifact.json

keptn version

Prints the version of the keptn CLI.

keptn version