Chapter 5. Pipelines CLI (tkn)

5.1. Installing tkn

Use the tkn CLI to manage Red Hat OpenShift Pipelines from a terminal. The following section describes how to install tkn on different platforms.

You can also find the URL to the latest binaries from the OpenShift Container Platform web console by clicking the ? icon in the upper-right corner and selecting Command Line Tools.

5.1.1. Installing Red Hat OpenShift Pipelines CLI (tkn) on Linux

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

Procedure

Download the relevant CLI.
Unpack the archive:
```
$ tar xvzf <file>
```
Place the tkn binary in a directory that is on your PATH.
To check your PATH, run:
```
$ echo $PATH
```

5.1.2. Installing Red Hat OpenShift Pipelines CLI (tkn) on Linux using an RPM

For Red Hat Enterprise Linux (RHEL) version 8, you can install the Red Hat OpenShift Pipelines CLI (tkn) 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.

Procedure

Register with Red Hat Subscription Manager:
```
# subscription-manager register
```
Pull the latest subscription data:
```
# subscription-manager refresh
```

List the available subscriptions:

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

In the output for the previous 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>
```

Enable the repositories required by Red Hat OpenShift Pipelines:

Linux (x86_64, amd64)

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

Linux on IBM Z and LinuxONE (s390x)

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

Linux on IBM Power Systems (ppc64le)

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

Install the openshift-pipelines-client package:
```
# yum install openshift-pipelines-client
```

After you install the CLI, it is available using the tkn command:

$ tkn version

5.1.3. Installing Red Hat OpenShift Pipelines CLI (tkn) on Windows

For Windows, the tkn CLI is provided as a zip archive.

Procedure

Download the CLI.
Unzip the archive with a ZIP program.
Add the location of your tkn.exe file to your PATH environment variable.
To check your PATH, open the command prompt and run the command:
```
C:\> path
```

5.1.4. Installing Red Hat OpenShift Pipelines CLI (tkn) on macOS

For macOS, the tkn CLI is provided as a tar.gz archive.

Procedure

Download the CLI.
Unpack and unzip the archive.
Move the tkn binary to a directory on your PATH.
To check your PATH, open a terminal window and run:
```
$ echo $PATH
```

5.2. Configuring the OpenShift Pipelines tkn CLI

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

5.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.

Prerequisites

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

Procedure

The following procedure enables tab completion for Bash.

Save the Bash completion code to a file:

$ tkn completion bash > tkn_bash_completion

Copy the file to /etc/bash_completion.d/:
```
$ sudo cp tkn_bash_completion /etc/bash_completion.d/
```
Alternatively, you can save the file to a local directory and source it from your .bashrc file instead.

Tab completion is enabled when you open a new terminal.

5.3. OpenShift Pipelines tkn reference

This section lists the basic tkn CLI commands.

5.3.1. Basic syntax

tkn [command or options] [arguments…]

5.3.2. Global options

--help, -h

5.3.3. Utility commands

5.3.3.1. tkn

Parent command for tkn CLI.

Example: Display all options

$ tkn

5.3.3.2. completion [shell]

Print shell completion code which must be evaluated to provide interactive completion. Supported shells are bash and zsh.

Example: Completion code for bash shell

$ tkn completion bash

5.3.3.3. version

Print version information of the tkn CLI.

Example: Check the tkn version

$ tkn version

5.3.4. Pipelines management commands

5.3.4.1. pipeline

Manage pipelines.

Example: Display help

$ tkn pipeline --help

5.3.4.2. pipeline delete

Delete a pipeline.

Example: Delete the mypipeline pipeline from a namespace

$ tkn pipeline delete mypipeline -n myspace

5.3.4.3. pipeline describe

Describe a pipeline.

Example: Describe the mypipeline pipeline

$ tkn pipeline describe mypipeline

5.3.4.4. pipeline list

Display a list of pipelines.

Example: Display a list of pipelines

$ tkn pipeline list

5.3.4.5. pipeline logs

Display the logs for a specific pipeline.

Example: Stream the live logs for the mypipeline pipeline

$ tkn pipeline logs -f mypipeline

5.3.4.6. pipeline start

Start a pipeline.

Example: Start the mypipeline pipeline

$ tkn pipeline start mypipeline

5.3.5. Pipeline run commands

5.3.5.1. pipelinerun

Manage pipeline runs.

Example: Display help

$ tkn pipelinerun -h

5.3.5.2. pipelinerun cancel

Cancel a pipeline run.

Example: Cancel the mypipelinerun pipeline run from a namespace

$ tkn pipelinerun cancel mypipelinerun -n myspace

5.3.5.3. pipelinerun delete

Delete a pipeline run.

Example: Delete pipeline runs from a namespace

$ tkn pipelinerun delete mypipelinerun1 mypipelinerun2 -n myspace

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

$ tkn pipelinerun delete -n myspace --keep 5 1

1: Replace 5 with the number of most recently executed pipeline runs you want to retain.

5.3.5.4. pipelinerun describe

Describe a pipeline run.

Example: Describe the mypipelinerun pipeline run in a namespace

$ tkn pipelinerun describe mypipelinerun -n myspace

5.3.5.5. pipelinerun list

List pipeline runs.

Example: Display a list of pipeline runs in a namespace

$ tkn pipelinerun list -n myspace

5.3.5.6. pipelinerun logs

Display the logs of a pipeline run.

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

$ tkn pipelinerun logs mypipelinerun -a -n myspace

5.3.6. Task management commands

5.3.6.1. task

Manage tasks.

Example: Display help

$ tkn task -h

5.3.6.2. task delete

Delete a task.

Example: Delete mytask1 and mytask2 tasks from a namespace

$ tkn task delete mytask1 mytask2 -n myspace

5.3.6.3. task describe

Describe a task.

Example: Describe the mytask task in a namespace

$ tkn task describe mytask -n myspace

5.3.6.4. task list

List tasks.

Example: List all the tasks in a namespace

$ tkn task list -n myspace

5.3.6.5. task logs

Display task logs.

Example: Display logs for the mytaskrun task run of the mytask task

$ tkn task logs mytask mytaskrun -n myspace

5.3.6.6. task start

Start a task.

Example: Start the mytask task in a namespace

$ tkn task start mytask -s <ServiceAccountName> -n myspace

5.3.7. Task run commands

5.3.7.1. taskrun

Manage task runs.

Example: Display help

$ tkn taskrun -h

5.3.7.2. taskrun cancel

Cancel a task run.

Example: Cancel the mytaskrun task run from a namespace

$ tkn taskrun cancel mytaskrun -n myspace

5.3.7.3. taskrun delete

Delete a TaskRun.

Example: Delete the mytaskrun1 and mytaskrun2 task runs from a namespace

$ tkn taskrun delete mytaskrun1 mytaskrun2 -n myspace

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

$ tkn taskrun delete -n myspace --keep 5 1

1: Replace 5 with the number of most recently executed task runs you want to retain.

5.3.7.4. taskrun describe

Describe a task run.

Example: Describe the mytaskrun task run in a namespace

$ tkn taskrun describe mytaskrun -n myspace

5.3.7.5. taskrun list

List task runs.

Example: List all the task runs in a namespace

$ tkn taskrun list -n myspace

5.3.7.6. taskrun logs

Display task run logs.

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

$ tkn taskrun logs -f mytaskrun -n myspace

5.3.8. Condition management commands

5.3.8.1. condition

Manage Conditions.

Example: Display help

$ tkn condition --help

5.3.8.2. condition delete

Delete a Condition.

Example: Delete the mycondition1 Condition from a namespace

$ tkn condition delete mycondition1 -n myspace

5.3.8.3. condition describe

Describe a Condition.

Example: Describe the mycondition1 Condition in a namespace

$ tkn condition describe mycondition1 -n myspace

5.3.8.4. condition list

List Conditions.

Example: List Conditions in a namespace

$ tkn condition list -n myspace

5.3.9. Pipeline Resource management commands

5.3.9.1. resource

Manage Pipeline Resources.

Example: Display help

$ tkn resource -h

5.3.9.2. 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.

5.3.9.3. resource delete

Delete a Pipeline Resource.

Example: Delete the myresource Pipeline Resource from a namespace

$ tkn resource delete myresource -n myspace

5.3.9.4. resource describe

Describe a Pipeline Resource.

Example: Describe the myresource Pipeline Resource

$ tkn resource describe myresource -n myspace

5.3.9.5. resource list

List Pipeline Resources.

Example: List all Pipeline Resources in a namespace

$ tkn resource list -n myspace

5.3.10. ClusterTask management commands

5.3.10.1. clustertask

Manage ClusterTasks.

Example: Display help

$ tkn clustertask --help

5.3.10.2. clustertask delete

Delete a ClusterTask resource in a cluster.

Example: Delete mytask1 and mytask2 ClusterTasks

$ tkn clustertask delete mytask1 mytask2

5.3.10.3. clustertask describe

Describe a ClusterTask.

Example: Describe the mytask ClusterTask

$ tkn clustertask describe mytask1

5.3.10.4. clustertask list

List ClusterTasks.

Example: List ClusterTasks

$ tkn clustertask list

5.3.10.5. clustertask start

Start ClusterTasks.

Example: Start the mytask ClusterTask

$ tkn clustertask start mytask

5.3.11. Trigger management commands

5.3.11.1. eventlistener

Manage EventListeners.

Example: Display help

$ tkn eventlistener -h

5.3.11.2. eventlistener delete

Delete an EventListener.

Example: Delete mylistener1 and mylistener2 EventListeners in a namespace

$ tkn eventlistener delete mylistener1 mylistener2 -n myspace

5.3.11.3. eventlistener describe

Describe an EventListener.

Example: Describe the mylistener EventListener in a namespace

$ tkn eventlistener describe mylistener -n myspace

5.3.11.4. eventlistener list

List EventListeners.

Example: List all the EventListeners in a namespace

$ tkn eventlistener list -n myspace

5.3.11.5. eventlistener logs

Display logs of an EventListener.

Example: Display the logs of the mylistener EventListener in a namespace

$ tkn eventlistener logs mylistener -n myspace

5.3.11.6. triggerbinding

Manage TriggerBindings.

Example: Display TriggerBindings help

$ tkn triggerbinding -h

5.3.11.7. triggerbinding delete

Delete a TriggerBinding.

Example: Delete mybinding1 and mybinding2 TriggerBindings in a namespace

$ tkn triggerbinding delete mybinding1 mybinding2 -n myspace

5.3.11.8. triggerbinding describe

Describe a TriggerBinding.

Example: Describe the mybinding TriggerBinding in a namespace

$ tkn triggerbinding describe mybinding -n myspace

5.3.11.9. triggerbinding list

List TriggerBindings.

Example: List all the TriggerBindings in a namespace

$ tkn triggerbinding list -n myspace

5.3.11.10. triggertemplate

Manage TriggerTemplates.

Example: Display TriggerTemplate help

$ tkn triggertemplate -h

5.3.11.11. triggertemplate delete

Delete a TriggerTemplate.

Example: Delete mytemplate1 and mytemplate2 TriggerTemplates in a namespace

$ tkn triggertemplate delete mytemplate1 mytemplate2 -n `myspace`

5.3.11.12. triggertemplate describe

Describe a TriggerTemplate.

Example: Describe the mytemplate TriggerTemplate in a namespace

$ tkn triggertemplate describe mytemplate -n `myspace`

5.3.11.13. triggertemplate list

List TriggerTemplates.

Example: List all the TriggerTemplates in a namespace

$ tkn triggertemplate list -n myspace

5.3.11.14. clustertriggerbinding

Manage ClusterTriggerBindings.

Example: Display ClusterTriggerBindings help

$ tkn clustertriggerbinding -h

5.3.11.15. clustertriggerbinding delete

Delete a ClusterTriggerBinding.

Example: Delete myclusterbinding1 and myclusterbinding2 ClusterTriggerBindings

$ tkn clustertriggerbinding delete myclusterbinding1 myclusterbinding2

5.3.11.16. clustertriggerbinding describe

Describe a ClusterTriggerBinding.

Example: Describe the myclusterbinding ClusterTriggerBinding

$ tkn clustertriggerbinding describe myclusterbinding

5.3.11.17. clustertriggerbinding list

List ClusterTriggerBindings.

Example: List all ClusterTriggerBindings

$ tkn clustertriggerbinding list

5.3.12. Hub interaction commands

Interact with Tekton Hub for resources such as tasks and pipelines.

5.3.12.1. 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.

5.3.12.2. hub downgrade

Downgrade an installed resource.

Example: Downgrade the mytask task in the mynamespace namespace to it’s older version

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

5.3.12.3. 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

5.3.12.4. 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

5.3.12.5. 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

5.3.12.6. 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

5.3.12.7. 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

5.3.12.8. 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