From e59eb97907e1feace79b4331736127467b0d215e Mon Sep 17 00:00:00 2001 From: Debashich Date: Mon, 22 Jun 2026 21:51:51 +0530 Subject: [PATCH 1/2] Add CONTEXT.md for AI agent consumption Add a concise CONTEXT.md describing common tkn workflows, conventions, output formats, and behavioral notes for AI agents. Fixes #2856 Assisted-by: Claude Sonnet 4.6 Signed-off-by: Debashich --- CONTEXT.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 CONTEXT.md diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 000000000..7478a5062 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,159 @@ +# tkn CLI Agent Context + +This file describes `tkn` conventions, output formats, and behavioral notes +for automated and agent-driven workflows. For contributing to tkn itself, +see `AGENTS.md`. + +--- + +## Resource Types + +Tekton has two layers: + +- Definitions (`pipeline`, `task`): reusable templates +- Runs (`pipelinerun`, `taskrun`): execution instances + +Supported verbs per resource type: + +| Resource | Verbs | +|---|---| +| `pipeline`, `task` | `list`, `describe`, `start`, `logs`, `delete`, `export` | +| `pipelinerun`, `taskrun` | `list`, `describe`, `logs`, `cancel`, `delete`, `export` | + +--- + +## Common Workflows + +List pipeline runs: + +```bash +tkn pipelinerun list --output json +``` + +Inspect run status: + +```bash +tkn pipelinerun describe --output json +tkn taskrun describe --output json +``` + +Get logs for the most recent run: + +```bash +tkn pipelinerun logs --last +tkn taskrun logs --last +``` + +Start a pipeline non-interactively: + +```bash +tkn pipeline start \ + --param = \ + --workspace name=,claimName= \ + --use-param-defaults \ + --skip-optional-workspace \ + --showlog +``` + +Re-run the most recent pipeline run: + +```bash +tkn pipeline start --last --use-param-defaults +``` + +Delete a run: + +```bash +tkn pipelinerun delete --force +tkn taskrun delete --force +``` + +--- + +## Output Formats + +| Command | JSON output | Notes | +|---|---|---| +| `list` | Yes | Supported on all resources | +| `describe` | Yes | Supported on all resources | +| `logs` | No | Plain text to stdout only | +| `start` | No | Prints run name to stdout on success | +| `delete` | No | Requires `--force` to skip confirmation | +| `export` | No | Outputs YAML (Kubernetes manifest) | + +`--output yaml` is available wherever `--output json` is supported. + +--- + +## Non-Interactive Usage + +`pipeline start` and `task start` prompt for missing parameters and workspaces +by default. In non-TTY environments, this blocks execution. + +For non-interactive use, pass: + +```bash +tkn pipeline start \ + --param = \ + --use-param-defaults \ + --skip-optional-workspace +``` + +`--use-param-defaults` applies schema defaults for unspecified parameters. If +a required parameter has no default and is not passed via `--param`, the +command prompts regardless. + +--- + +## Exit Codes + +`tkn pipelinerun logs` defines the following exit codes: + +| Code | Meaning | +|---|---| +| 0 | PipelineRun succeeded | +| 1 | PipelineRun failed | +| 2 | No status conditions available | + +Exit code behavior is only documented for `pipelinerun logs`. Other commands +do not define stable exit code semantics. + +--- + +## Behavioral Notes + +**`taskrun logs` exit code does not reflect run outcome.** A failed TaskRun +exits 0. To check TaskRun outcome, inspect `.status.conditions[0].status`: + +```bash +tkn taskrun describe --output json +``` + +**`delete` requires `--force` on all resources.** Without `-f`, the command +prompts for confirmation. + +**`--last` targets the most recent run by creation time.** In concurrent +environments, capture the run name from `pipeline start` stdout and pass it +explicitly to subsequent commands. + +**`logs` does not support structured output.** Log content goes to stdout; +errors go to stderr. + +**`export` outputs YAML only.** Use `describe --output json` for structured +status inspection. + +--- + +## Common Flags + +| Flag | Commands | Purpose | +|---|---|---| +| `--output json` | `list`, `describe` | Machine-readable output | +| `--last` | `logs`, `start`, `describe` | Target most recent run | +| `--use-param-defaults` | `start` | Use schema defaults for unspecified params | +| `--skip-optional-workspace` | `start` | Skip prompts for optional workspaces | +| `--force`, `-f` | `delete` | Skip confirmation prompt | +| `--showlog` | `start` | Stream logs after starting | +| `--namespace`, `-n` | all | Override kubeconfig namespace | +| `--param`, `-p` | `start` | Pass parameter as `=` | +| `--workspace`, `-w` | `start` | Pass workspace binding | \ No newline at end of file From 2605ccd01a74d3faf723eb878ee803eedecb033d Mon Sep 17 00:00:00 2001 From: Debashich Date: Tue, 14 Jul 2026 21:56:58 +0530 Subject: [PATCH 2/2] docs: address review feedback for CONTEXT.md --- CONTEXT.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 7478a5062..d1658cd5c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -17,8 +17,13 @@ Supported verbs per resource type: | Resource | Verbs | |---|---| -| `pipeline`, `task` | `list`, `describe`, `start`, `logs`, `delete`, `export` | -| `pipelinerun`, `taskrun` | `list`, `describe`, `logs`, `cancel`, `delete`, `export` | +| `pipeline` | `list`, `describe`, `start`, `logs`, `delete` | +| `task` | `list`, `describe`, `start`, `logs`, `delete` | +| `pipelinerun`, `taskrun` | `list`, `describe`, `logs`, `cancel`, `delete` | + +Other resource types (`customrun`, `eventlistener`, `triggerbinding`, +`triggertemplate`, `clustertriggerbinding`, `bundle`, and `hub`) support +subsets of `list`, `describe`, and `delete`. --- @@ -76,10 +81,10 @@ tkn taskrun delete --force |---|---|---| | `list` | Yes | Supported on all resources | | `describe` | Yes | Supported on all resources | +| `start` | Yes | Supported by `pipeline start` and `task start` | | `logs` | No | Plain text to stdout only | -| `start` | No | Prints run name to stdout on success | | `delete` | No | Requires `--force` to skip confirmation | -| `export` | No | Outputs YAML (Kubernetes manifest) | +| `export` | No | Outputs YAML instead of JSON | `--output yaml` is available wherever `--output json` is supported. @@ -107,7 +112,10 @@ command prompts regardless. ## Exit Codes -`tkn pipelinerun logs` defines the following exit codes: +By default, `tkn pipelinerun logs` exits 0 after streaming logs, regardless +of run outcome. + +With `--exit-with-pipelinerun-error` (`-E`), the exit code reflects run status: | Code | Meaning | |---|---| @@ -115,15 +123,16 @@ command prompts regardless. | 1 | PipelineRun failed | | 2 | No status conditions available | -Exit code behavior is only documented for `pipelinerun logs`. Other commands -do not define stable exit code semantics. +`-E` is also available on `pipeline start` when used with `--showlog`. + +`taskrun logs` does not support this flag — it always exits 0. --- ## Behavioral Notes -**`taskrun logs` exit code does not reflect run outcome.** A failed TaskRun -exits 0. To check TaskRun outcome, inspect `.status.conditions[0].status`: +**`taskrun logs` has no equivalent of `-E`.** To check TaskRun outcome, +inspect `.status.conditions[0].status`: ```bash tkn taskrun describe --output json @@ -148,12 +157,13 @@ status inspection. | Flag | Commands | Purpose | |---|---|---| -| `--output json` | `list`, `describe` | Machine-readable output | -| `--last` | `logs`, `start`, `describe` | Target most recent run | -| `--use-param-defaults` | `start` | Use schema defaults for unspecified params | +| `--output json` | `list`, `describe`, `pipeline start` | Machine-readable output | +| `--last` | `logs`, `start`, `pipelinerun describe`, `taskrun describe` | Target the most recent run | +| `--use-param-defaults` | `start` | Use schema defaults for unspecified parameters | | `--skip-optional-workspace` | `start` | Skip prompts for optional workspaces | | `--force`, `-f` | `delete` | Skip confirmation prompt | | `--showlog` | `start` | Stream logs after starting | -| `--namespace`, `-n` | all | Override kubeconfig namespace | +| `--exit-with-pipelinerun-error`, `-E` | `pipelinerun logs`, `pipeline start` | Exit with PipelineRun status (0=success, 1=failed, 2=unknown) | +| `--namespace`, `-n` | all | Override the kubeconfig namespace | | `--param`, `-p` | `start` | Pass parameter as `=` | | `--workspace`, `-w` | `start` | Pass workspace binding | \ No newline at end of file