Tekton CLI

Tekton CLI (tkn) cheatsheet — manage Kubernetes-native CI/CD pipelines. tkn pipeline start, tkn pipelinerun logs, tkn task list. Trigger and inspect Tekton resources.

8 min read

What it is

The tkn CLI is your command-line interface for interacting with Tekton Pipelines, a Kubernetes-native framework for creating CI/CD systems. You use tkn to manage Tekton resources, trigger pipelines, and inspect their execution.

Installation

Linux

# Using Go (if you have Go installed)
go install github.com/tektoncd/cli/cmd/tkn@latest

# Using release binaries (check releases page for latest version)
# Example for v0.34.1
curl -sLO https://github.com/tektoncd/cli/releases/download/v0.34.1/tkn_0.34.1_Linux_x86_64.tar.gz
tar -zxvf tkn_0.34.1_Linux_x86_64.tar.gz
sudo mv tkn /usr/local/bin/
rm tkn_0.34.1_Linux_x86_64.tar.gz

macOS

# Using Homebrew
brew install tkn-cli

# Using release binaries (check releases page for latest version)
# Example for v0.34.1
curl -sLO https://github.com/tektoncd/cli/releases/download/v0.34.1/tkn_0.34.1_Darwin_x86_64.tar.gz
tar -zxvf tkn_0.34.1_Darwin_x86_64.tar.gz
sudo mv tkn /usr/local/bin/
rm tkn_0.34.1_Darwin_x86_64.tar.gz

Windows

# Using release binaries (check releases page for latest version)
# Example for v0.34.1
curl -sLO https://github.com/tektoncd/cli/releases/download/v0.34.1/tkn_0.34.1_Windows_x86_64.zip
Expand-Archive -Path tkn_0.34.1_Windows_x86_64.zip -DestinationPath .
# Move tkn.exe to a directory in your PATH, e.g., C:\Program Files\
# Remove the zip file

Verify installation:

tkn version

Core Concepts

Pipeline: A defined sequence of Tasks that are executed in order.
Task: A collection of Steps that are executed in a Pod. A Task can be run independently or as part of a Pipeline.
PipelineRun: An instance of a Pipeline. It represents a single execution of a Pipeline.
TaskRun: An instance of a Task. It represents a single execution of a Task.
Resource: Refers to Tekton resources like Pipelines, Tasks, PipelineRuns, TaskRuns, Workspaces, etc., that are defined as Kubernetes Custom Resources.
Workspace: A volume that can be shared between Steps in a Task or Tasks in a Pipeline.

Commands / Usage

Managing Tekton Resources

Listing Resources

# List all pipelines in the current namespace
tkn pipelist

# List all tasks in the current namespace
tkn tasklist

# List all pipeline runs in the current namespace
tkn pipelineresult list

# List all task runs in the current namespace
tkn taskrun list

# List all workspaces in the current namespace
tkn workspacelist

# List all clustersources in the current namespace
tkn clustersourcelist

# List all triggertemplates in the current namespace
tkn triggertemplatelist

# List all triggersbindings in the current namespace
tkn triggerbindinglist

# List all eventlisteners in the current namespace
tkn eventlistenerlist

# List all conditions in the current namespace
tkn conditionlist

# List all custom tasks in the current namespace
tkn customtasklist

# List all configurations in the current namespace
tkn configlist

Describing Resources

# Get details of a specific pipeline named 'my-pipeline'
tkn pipeline describe my-pipeline

# Get details of a specific task named 'build-task'
tkn task describe build-task

# Get details of a specific pipeline run named 'my-pipeline-run-abcde'
tkn pipelineresult describe my-pipeline-run-abcde

# Get details of a specific task run named 'build-task-run-12345'
tkn taskrun describe build-task-run-12345

# Get details of a specific workspace named 'shared-data'
tkn workspace describe shared-data

Deleting Resources

# Delete a pipeline named 'old-pipeline'
tkn pipeline delete old-pipeline

# Delete a task named 'cleanup-task'
tkn task delete cleanup-task

# Delete a pipeline run named 'stale-pipeline-run-xyz'
tkn pipelineresult delete stale-pipeline-run-xyz

Creating Resources from File

# Create a pipeline from a YAML file
tkn pipeline apply -f pipeline.yaml

# Create a task from a YAML file
tkn task apply -f task.yaml

# Create multiple resources from a directory
tkn resource apply -f ./tekton-resources/

Triggering and Monitoring Pipeline Runs

Starting a Pipeline Run

# Start a pipeline run for 'my-pipeline'
tkn pipeline start my-pipeline

# Start a pipeline run with parameters
tkn pipeline start my-pipeline -p image-name=my-docker-image -p tag=latest

# Start a pipeline run with specific service account
tkn pipeline start my-pipeline -s pipeline-sa

# Start a pipeline run and follow its logs
tkn pipeline start my-pipeline --showlog

# Start a pipeline run with workspaces
tkn pipeline start my-pipeline -w name=source-dir,volumeClaimName=my-pvc -w name=output-dir,emptyDir=true

# Start a pipeline run and wait for it to complete
tkn pipeline start my-pipeline --wait

Monitoring Pipeline Runs

# Get the status of the latest pipeline run for 'my-pipeline'
tkn pipelineresult logs --pipeline my-pipeline

# Get the status of a specific pipeline run 'my-pipeline-run-abcde'
tkn pipelineresult logs my-pipeline-run-abcde

# Follow the logs of a specific pipeline run 'my-pipeline-run-abcde'
tkn pipelineresult logs my-pipeline-run-abcde -f

# Get the logs of a specific task run within a pipeline run
tkn taskrun logs my-pipeline-run-abcde --task-name build-task

# Get the logs of a specific step within a task run
tkn taskrun logs my-pipeline-run-abcde --task-name build-task --step build

Listing and Describing Pipeline Runs

# List all pipeline runs
tkn pipelineresult list

# List pipeline runs for a specific pipeline
tkn pipelineresult list --pipeline my-pipeline

# Describe a specific pipeline run
tkn pipelineresult describe my-pipeline-run-abcde

Managing Task Runs

Starting a Task Run

# Start a task run for 'build-task'
tkn task start build-task

# Start a task run with parameters
tkn task start build-task -p commit=abcdef12345

# Start a task run with workspaces
tkn task start build-task -w name=source,volumeClaimName=my-source-pvc

# Start a task run and follow its logs
tkn task start build-task --showlog

Monitoring Task Runs

# Get the status of the latest task run for 'build-task'
tkn taskrun logs --task build-task

# Get the status of a specific task run 'build-task-run-12345'
tkn taskrun logs build-task-run-12345

# Follow the logs of a specific task run 'build-task-run-12345'
tkn taskrun logs build-task-run-12345 -f

Listing and Describing Task Runs

# List all task runs
tkn taskrun list

# List task runs for a specific task
tkn taskrun list --task build-task

# Describe a specific task run
tkn taskrun describe build-task-run-12345

Working with Triggers

# Create a trigger template from a file
tkn triggertemplate apply -f trigger-template.yaml

# Create a trigger binding from a file
tkn triggerbinding apply -f trigger-binding.yaml

# Create an event listener from a file
tkn eventlistener apply -f event-listener.yaml

# List all trigger templates
tkn triggertemplatelist

# List all trigger bindings
tkn triggerbindinglist

# List all event listeners
tkn eventlistenerlist

# Describe a specific event listener
tkn eventlistener describe my-event-listener

Configuration and Context

# Show the current Tekton configuration
tkn config list

# Set the namespace for Tekton commands
tkn config set namespace kube-pipelines

# Set the context for Tekton commands (useful if you have multiple K8s contexts)
tkn config set context my-tekton-context

# View Tekton CLI version
tkn version

Common Patterns

Following logs of the latest pipeline run:

tkn pipelineresult logs --pipeline my-pipeline -f

Starting a pipeline run and waiting for completion:

tkn pipeline start my-pipeline --wait

Listing all completed pipeline runs:

tkn pipelineresult list | grep Succeeded

Cleaning up old pipeline runs (e.g., more than 7 days old):

# First, list runs to confirm deletion targets
tkn pipelineresult list -A --since 7d

# Then, delete them
tkn pipelineresult list -A --since 7d -d

(Note: -A lists across all namespaces, use cautiously)

Downloading Tekton Task/Pipeline definitions from a Git repository:

# Clone the repository first
git clone https://github.com/tektoncd/catalog.git
cd catalog/pipelines/buildah/0.1/
tkn resource apply -f ./task.yaml # Or pipeline.yaml

Creating a PipelineRun from a Git commit:

# Assuming your pipeline is configured to take a commit SHA as a parameter
tkn pipeline start my-pipeline -p commit-sha=a1b2c3d4e5f6 --showlog

Debugging a failed PipelineRun by inspecting its TaskRuns:

# List failed pipeline runs
tkn pipelineresult list | grep Failed

# Get the name of a failed pipeline run, e.g., 'my-pipeline-run-failed-xyz'
# Then list its task runs
tkn taskrun list --pipeline-run my-pipeline-run-failed-xyz

# Inspect the logs of a specific failed task run
tkn taskrun logs my-pipeline-run-failed-xyz

Gotchas

Namespace Scope: Most tkn commands operate within the currently configured Kubernetes namespace. Use the -n or --namespace flag for explicit control if needed, or tkn config set namespace <namespace> to change the default.
Resource Naming: Tekton resource names must be unique within their namespace. Be mindful of naming conflicts when applying resources.
--showlog vs. --wait: --showlog streams logs during execution but doesn’t wait for completion. --wait blocks until the resource (PipelineRun or TaskRun) finishes, but doesn’t automatically show logs unless combined with other flags or commands. Use tkn pipelineresult logs <run-name> after --wait if you need logs.
tkn resource apply vs. tkn pipeline apply / tkn task apply: tkn resource apply is a general command that can apply any Tekton resource defined in a file or directory. tkn pipeline apply and tkn task apply are specific to pipelines and tasks respectively and can be more convenient for those types.
tkn pipelineresult list vs. tkn pipelineresult logs: list shows the status and metadata of runs, while logs fetches and displays the execution logs. You often use list to find a run name, then logs to inspect it.
Default Service Account: If not specified, Tekton uses the default service account in the namespace for running Steps. Ensure this service account has the necessary permissions. Use the -s or --serviceaccount flag to override.
Workspace Configuration: When using workspaces, ensure the volumeClaimTemplate (for PVCs) or other volume sources are correctly defined and accessible in your cluster. emptyDir is the simplest for temporary storage.
Triggering External Resources: When using Triggers, remember that the EventListener acts as a webhook endpoint. You need to configure your external source (e.g., GitHub webhook) to send events to the EventListener’s exposed service URL.