Pipelines CLI (tkn) reference

Red Hat OpenShift Pipelines 1.23

The tkn CLI reference for OpenShift Pipelines

Red Hat OpenShift Documentation Team

Abstract

This document provides information about how to install, configure, and use the tkn CLI tool for OpenShift Pipelines.

Chapter 1. Installing tkn

Use the CLI tool to manage Red Hat OpenShift Pipelines from a terminal. You can install the CLI tool on different platforms.

Note

Both the archives and the RPMs contain the following executables:

  • tkn
  • tkn-pac
  • opc
Note

The openshift-pipelines-client RPM is deprecated and might be removed in a future release of Red Hat OpenShift Pipelines. Use standalone binaries for the tkn, tkn-pac, and opc CLI tools instead of the RPM package. Download the latest CLI binaries from This content is not included.Red Hat OpenShift Pipelines binaries.

Important

Running Red Hat OpenShift Pipelines with the opc CLI tool is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

1.1. Installing the Red Hat OpenShift Pipelines CLI on Linux

For Linux distributions, you can download the CLI as a tar.gz archive.

Procedure

  1. Download the relevant CLI tool.

  1. Unpack the archive: 

    $ tar xvzf <file>
  2. Add the location of your tkn, tkn-pac, and opc files to your PATH environment variable.

  3. To check your PATH, run the following command: 

    $ echo $PATH

1.2. Installing the Red Hat OpenShift Pipelines CLI on Linux using an RPM

For Red Hat Enterprise Linux (RHEL) version 8, you can install the Red Hat OpenShift Pipelines CLI as an RPM.

Prerequisites

  • You have an active OpenShift Container Platform subscription on your Red Hat account.
  • You have root or sudo privileges on your local system.
Note

The openshift-pipelines-client RPM is deprecated and might be removed in a future release of Red Hat OpenShift Pipelines. Use standalone binaries for the tkn, tkn-pac, and opc CLI tools instead of the RPM package. Download the latest CLI binaries from This content is not included.Red Hat OpenShift Pipelines binaries.

Procedure

  1. Register with Red Hat Subscription Manager: 

    # subscription-manager register

  2. Pull the latest subscription data: 

    # subscription-manager refresh

  3. List the available subscriptions: 

    # subscription-manager list --available --matches '*pipelines*'

  4. In the output for the earlier command, find the pool ID for your OpenShift Container Platform subscription and attach the subscription to the registered system: 

    # subscription-manager attach --pool=<pool_id>

  5. Enable the repositories required by Red Hat OpenShift Pipelines:

    • Linux (x86_64, amd64) 

      # subscription-manager repos --enable="pipelines-1.23-for-rhel-8-x86_64-rpms"

    • Linux on IBM zSystems and IBM® LinuxONE (s390x) 

      # subscription-manager repos --enable="pipelines-1.23-for-rhel-8-s390x-rpms"

    • Linux on IBM Power (ppc64le) 

      # subscription-manager repos --enable="pipelines-1.23-for-rhel-8-ppc64le-rpms"

    • Linux on ARM (aarch64, arm64) 

      # subscription-manager repos --enable="pipelines-1.23-for-rhel-8-aarch64-rpms"

  6. Install the openshift-pipelines-client package: 

    # yum install openshift-pipelines-client

    After you install the CLI, you can use it with the tkn command: 

    $ tkn version

1.3. Installing the Red Hat OpenShift Pipelines CLI on Windows

For Windows, you can download the CLI as a zip archive.

Procedure

  1. Download the Content from mirror.openshift.com is not included.CLI tool.
  1. Extract the archive with a ZIP program.
  2. Add the location of your tkn, tkn-pac, and opc files to your PATH environment variable.

  3. To check your PATH, run the following command: 

    C:\> path

1.4. Installing the Red Hat OpenShift Pipelines CLI on macOS

For macOS, you can download the CLI as a tar.gz archive.

Procedure

  1. Download the relevant CLI tool.

  1. Unpack and extract the archive.
  2. Add the location of your tkn, tkn-pac, and opc files to your PATH environment variable.

  3. To check your PATH, run the following command: 

    $ echo $PATH

Chapter 2. Configuring the OpenShift Pipelines tkn CLI

Configure the Red Hat OpenShift Pipelines tkn CLI to enable tab completion.

2.1. Enabling tab completion

After you install the tkn CLI, you can enable tab completion to automatically complete tkn commands or suggest options when you press Tab.

After you install the tkn CLI, you can enable tab completion to automatically complete tkn commands or suggest options when you press Tab.

Prerequisites

  • You must have the tkn CLI tool installed.
  • You must have bash-completion installed on your local system.

Procedure

  1. Save the Bash completion code to a file: 

    $ tkn completion bash > tkn_bash_completion

  2. Copy the file to /etc/bash_completion.d/: 

    $ sudo cp tkn_bash_completion /etc/bash_completion.d/

    Or, you can save the file to a local directory and source it from your .bashrc file instead.

    Opening a new terminal enables tab completion.

Chapter 3. OpenShift Pipelines tkn reference

Use the tkn CLI to manage pipelines, tasks, pipeline runs, and other OpenShift Pipelines resources from the command line.

Basic syntax
$ tkn [command or options] [arguments...]
Global options
--help, -h

3.1. Utility commands

You can use utility commands in the tkn CLI to manage the CLI environment. These commands allow you to check the version and enable shell prompt completion.

3.1.1. tkn

Parent command for tkn CLI.

Example: Display all options

$ tkn

3.1.2. completion [shell]

Print shell prompt completion code that you must evaluate to give interactive completion. Supported shells are bash and zsh.

Example: Completion code for the bash shell prompt

$ tkn completion bash

3.1.3. version

Print version information of the tkn CLI.

Example: Check the tkn version

$ tkn version

3.2. Pipelines management commands

Use the tkn pipeline commands to create, list, start, delete, and describe pipelines from the command line.

3.2.1. pipeline

Manage pipelines.

Example: Display help

$ tkn pipeline --help

3.2.2. pipeline delete

Delete a pipeline.

Example: Delete a pipeline from a namespace

$ tkn pipeline delete <pipeline_name> -n <namespace_name>

3.2.3. pipeline describe

Describe a pipeline.

Example: Describe a pipeline

$ tkn pipeline describe <pipeline_name>

3.2.4. pipeline list

Display a list of pipelines.

Example: Display a list of pipelines

$ tkn pipeline list

3.2.5. pipeline logs

Display the logs for a specific pipeline.

Example: Stream the live logs for a pipeline

$ tkn pipeline logs -f <pipeline_name>

3.2.6. pipeline start

Start a pipeline.

Example: Start a pipeline

$ tkn pipeline start <pipeline_name>

3.3. Pipeline run commands

Use the tkn pipelinerun commands to list, describe, cancel, and delete pipeline runs from the command line.

3.3.1. pipelinerun

Manage pipeline runs.

Example: Display help

$ tkn pipelinerun -h

3.3.2. pipelinerun cancel

Cancel a pipeline run.

Example: Cancel a pipeline run from a namespace

$ tkn pipelinerun cancel <pipeline_run_name> -n <namespace_name>

3.3.3. pipelinerun delete

Delete a pipeline run.

Example: Delete pipeline runs from a namespace

$ tkn pipelinerun delete <pipeline_run_name_1> <pipeline_run_name_2> -n <namespace_name>

Example: Delete all pipeline runs from a namespace, except the five most recently executed pipeline runs

$ tkn pipelinerun delete -n <namespace_name> --keep 5

<namespace_name>
Replace 5 with the number of most recently executed pipeline runs you want to retain.

Example: Delete all pipelines

$ tkn pipelinerun delete --all

Note

Starting with Red Hat OpenShift Pipelines 1.6, the tkn pipelinerun delete --all command does not delete any resources that are in the running state.

3.3.4. pipelinerun describe

Describe a pipeline run.

Example: Describe a pipeline run in a namespace

$ tkn pipelinerun describe <pipeline_run_name> -n <namespace_name>

3.3.5. pipelinerun list

List pipeline runs.

Example: Display a list of pipeline runs in a namespace

$ tkn pipelinerun list -n <namespace_name>

3.3.6. pipelinerun logs

Display the logs of a pipeline run.

Example: Display the logs of a pipeline run with all tasks and steps in a namespace

$ tkn pipelinerun logs <pipeline_run_name> -a -n <namespace_name>

3.4. Task management commands

Use the tkn task commands to create, list, start, delete, and describe tasks from the command line.

3.4.1. task

Manage tasks.

Example: Display help

$ tkn task -h

3.4.2. task delete

Delete a task.

Example: Delete tasks from a namespace

$ tkn task delete <task_name_1> <task_name_2> -n <namespace_name>

3.4.3. task describe

Describe a task.

Example: Describe a task in a namespace

$ tkn task describe <task_name> -n <namespace_name>

3.4.4. task list

List tasks.

Example: List all the tasks in a namespace

$ tkn task list -n <namespace_name>

3.4.5. task start

Start a task.

Example: Start a task in a namespace

$ tkn task start <task_name> -s <service_account_name> -n <namespace_name>

3.5. Task run commands

Use the tkn taskrun commands to list, describe, cancel, and delete task runs from the command line.

3.5.1. taskrun

Manage task runs.

Example: Display help

$ tkn taskrun -h

3.5.2. taskrun cancel

Cancel a task run.

Example: Cancel a task run from a namespace

$ tkn taskrun cancel <task_run_name> -n <namespace_name>

3.5.3. taskrun delete

Delete a TaskRun.

Example: Delete task runs from a namespace

$ tkn taskrun delete <task_run_name_1> <task_run_name_2> -n <namespace_name>

Example: Delete all but the five most recently executed task runs from a namespace

$ tkn taskrun delete -n <namespace_name> --keep 5

<namespace_name>
Replace 5 with the number of most recently executed task runs you want to retain.

3.5.4. taskrun describe

Describe a task run.

Example: Describe a task run in a namespace

$ tkn taskrun describe <task_run_name> -n <namespace_name>

3.5.5. taskrun list

List task runs.

Example: List all the task runs in a namespace

$ tkn taskrun list -n <namespace_name>

3.5.6. taskrun logs

Display task run logs.

Example: Display live logs for a task run in a namespace

$ tkn taskrun logs -f <task_run_name> -n <namespace_name>

3.6. Pipeline resource management commands

You can use the tkn resource commands to manage, create, view, and interact with pipeline resources in your namespace.

resource

Manage pipeline resources.

Example: Display help

$ tkn resource -h

resource create

Create a pipeline resource.

Example: Create a pipeline resource in a namespace

$ tkn resource create -n myspace

This is an interactive command that asks for input on the name of the resource, type of the resource, and the values based on the type of the resource.

resource delete

Delete a pipeline resource.

Example: Delete the myresource pipeline resource from a namespace

$ tkn resource delete myresource -n myspace

resource describe

Describe a pipeline resource.

Example: Describe the myresource pipeline resource

$ tkn resource describe myresource -n myspace

resource list

List pipeline resources.

Example: List all pipeline resources in a namespace

$ tkn resource list -n myspace

3.7. Trigger management commands

You can use the tkn trigger management commands to manage, creating, viewing, and interacting with EventListener, TriggerBinding, TriggerTemplate, and ClusterTriggerBinding resources in your namespace.

eventlistener

Manage event listeners.

Example: Display help

$ tkn eventlistener -h

eventlistener delete

Delete an event listener.

Example: Delete mylistener1 and mylistener2 event listeners in a namespace

$ tkn eventlistener delete mylistener1 mylistener2 -n myspace

eventlistener describe

Describe an event listener.

Example: Describe the mylistener event listener in a namespace

$ tkn eventlistener describe mylistener -n myspace

eventlistener list

List event listeners.

Example: List all the event listeners in a namespace

$ tkn eventlistener list -n myspace

eventlistener logs

Display logs of an event listener.

Example: Display the logs of the mylistener event listener in a namespace

$ tkn eventlistener logs mylistener -n myspace

triggerbinding

Manage trigger bindings.

Example: Display trigger bindings help

$ tkn triggerbinding -h

triggerbinding delete

Delete a trigger binding.

Example: Delete mybinding1 and mybinding2 trigger bindings in a namespace

$ tkn triggerbinding delete mybinding1 mybinding2 -n myspace

triggerbinding describe

Describe a trigger binding.

Example: Describe the mybinding trigger binding in a namespace

$ tkn triggerbinding describe mybinding -n myspace

triggerbinding list

List trigger bindings.

Example: List all the trigger bindings in a namespace

$ tkn triggerbinding list -n myspace

triggertemplate

Manage trigger templates.

Example: Display trigger template help

$ tkn triggertemplate -h

triggertemplate delete

Delete a trigger template.

Example: Delete mytemplate1 and mytemplate2 trigger templates in a namespace

$ tkn triggertemplate delete mytemplate1 mytemplate2 -n `myspace`

triggertemplate describe

Describe a trigger template.

Example: Describe the mytemplate trigger template in a namespace

$ tkn triggertemplate describe mytemplate -n `myspace`

triggertemplate list

List trigger templates.

Example: List all the trigger templates in a namespace

$ tkn triggertemplate list -n myspace

clustertriggerbinding

Manage cluster trigger bindings.

Example: Display cluster trigger bindings help

$ tkn clustertriggerbinding -h

clustertriggerbinding delete

Delete a cluster trigger binding.

Example: Delete myclusterbinding1 and myclusterbinding2 cluster trigger bindings

$ tkn clustertriggerbinding delete myclusterbinding1 myclusterbinding2

clustertriggerbinding describe

Describe a cluster trigger binding.

Example: Describe the myclusterbinding cluster trigger binding

$ tkn clustertriggerbinding describe myclusterbinding

clustertriggerbinding list

List cluster trigger bindings.

Example: List all cluster trigger bindings

$ tkn clustertriggerbinding list

3.8. Hub interaction commands

You can use the tkn hub commands to interact with the Tekton Hub and manage resources such as tasks and pipelines.

hub

Interact with hub.

Example: Display help

$ tkn hub -h

Example: Interact with a hub API server

$ tkn hub --api-server https://api.hub.tekton.dev

Note

For each example, to get the corresponding sub-commands and flags, run tkn hub <command> --help.

hub downgrade

Roll back an installed resource to an earlier version.

Example: Roll back the mytask task in the mynamespace namespace to its older version

$ tkn hub downgrade task mytask --to version -n mynamespace

hub get

Get a resource manifest by its name, kind, catalog, and version.

Example: Get the manifest for a specific version of the myresource pipeline or task from the tekton catalog

$ tkn hub get [pipeline | task] myresource --from tekton --version version

hub info

Display information about a resource by its name, kind, catalog, and version.

Example: Display information about a specific version of the mytask task from the tekton catalog

$ tkn hub info task mytask --from tekton --version version

hub install

Install a resource from a catalog by its kind, name, and version.

Example: Install a specific version of the mytask task from the tekton catalog in the mynamespace namespace

$ tkn hub install task mytask --from tekton --version version -n mynamespace

hub reinstall

Reinstall a resource by its kind and name.

Example: Reinstall a specific version of the mytask task from the tekton catalog in the mynamespace namespace

$ tkn hub reinstall task mytask --from tekton --version version -n mynamespace

hub search

Search a resource by a combination of name, kind, and tags.

Example: Search a resource with a tag cli

$ tkn hub search --tags cli

hub upgrade

Upgrade an installed resource.

Example: Upgrade the installed mytask task in the mynamespace namespace to a new version

$ tkn hub upgrade task mytask --to version -n mynamespace

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.