openshift-pipelines · chmouel · Jun 27, 2025
diff --git a/docs/content/docs/guide/cli.md b/docs/content/docs/guide/cli.md
@@ -409,6 +409,111 @@ You can specify a different directory than the current one by using the -d/--dir
 
 {{< /details >}}
 
+{{< details "tkn pac cel" >}}
+
+### CEL Expression Evaluator
+
+`tkn pac cel` — Evaluate CEL (Common Expression Language) expressions interactively with webhook payloads.
+
+This command allows you to test and debug CEL expressions as they would be evaluated by Pipelines-as-Code, using real webhook payloads and headers. It supports interactive and non-interactive modes, provider auto-detection, and persistent history.
+
+To be able to have the CEL evaluator working, you need to have the payload and the headers available in a file. The best way to do this is to go to the webhook configuration on your git provider and copy the payload and headers to different files.
+
+The payload is the JSON content of the webhook request, The headers file supports multiple formats:
+
+1. **Plain HTTP headers format** (as shown above)
+2. **JSON format**:
+
+   ```json
+   {
+     "X-GitHub-Event": "pull_request",
+     "Content-Type": "application/json",
+     "User-Agent": "GitHub-Hookshot/2d5e4d4"
+   }
+   ```
+
+3. **Gosmee-generated shell scripts**: The command automatically detects and parses shell scripts generated by [gosmee](https://github.com/chmouel/gosmee) which are generated when using the `--save` feature, extracting headers from curl commands with `-H` flags:
+
+   ```bash
+   #!/usr/bin/env bash
+   curl -X POST "http://localhost:8080/" \
+     -H "X-GitHub-Event: pull_request" \
+     -H "Content-Type: application/json" \
+     -H "User-Agent: GitHub-Hookshot/2d5e4d4" \
+     -d @payload.json
+   ```
+
+#### Usage
+
+```shell
+tkn pac cel -b <body.json> -H <headers.txt>
+```
+
+* `-b, --body`: Path to JSON body file (webhook payload)
+* `-H, --headers`: Path to headers file (plain text, JSON, or gosmee script)
+* `-p, --provider`: Provider (auto, github, gitlab, bitbucket-cloud, bitbucket-datacenter, gitea)
+
+#### Interactive Mode
+
+If run in a terminal, you'll get a prompt:
+
+```console
+CEL expression> 
+```
+
+* Use ↑/↓ arrows to navigate history.
+* History is saved and loaded automatically.
+* Press Enter on an empty line to exit.
+
+#### Non-Interactive Mode
+
+Pipe expressions via stdin:
+
+```shell
+echo 'event == "pull_request"' | tkn pac cel -b body.json -H headers.txt
+```
+
+#### Available Variables
+
+* **Direct variables** (top-level, as per PAC documentation):
+  * `event` — event type (push, pull_request)
+  * `target_branch` — target branch name
+  * `source_branch` — source branch name
+  * `target_url` — target repository URL
+  * `source_url` — source repository URL
+  * `event_title` — PR title or commit message
+
+* **Webhook payload** (`body.*`): All fields from the webhook JSON.
+* **HTTP headers** (`headers.*`): All HTTP headers.
+* **Files** (`files.*`): Always empty in CLI mode.  
+  **Note:** `fileChanged`, `fileDeleted`, `fileModified` and similar functions are **not implemented yet** in the CLI.
+* **PAC Parameters** (`pac.*`): All variables for backward compatibility.
+
+#### Example Expressions
+
+```text
+event == "pull_request" && target_branch == "main"
+event == "pull_request" && source_branch.matches(".*feat/.*")
+body.action == "synchronize"
+!body.pull_request.draft
+headers['x-github-event'] == "pull_request"
+event == "pull_request" && target_branch != "experimental"
+```
+
+#### Limitations
+
+* `files.*` variables are always empty in CLI mode.
+* Functions like `fileChanged`, `fileDeleted`, `fileModified` are **not implemented yet** in the CLI.
+
+#### Cross-Platform History
+
+* History is saved in a cache directory:
+  * Linux/macOS: `~/.cache/tkn-pac/cel-history`
+  * Windows: `%USERPROFILE%\.cache\tkn-pac\cel-history`
+* The directory is created automatically if it does not exist.
+
+{{< /details >}}
+
 ## Screenshot
 
 ![tkn-plug-in](/images/tkn-pac-cli.png)
diff --git a/go.mod b/go.mod
@@ -9,6 +9,7 @@ require (
 	code.gitea.io/sdk/gitea v0.21.0
 	github.com/AlecAivazis/survey/v2 v2.3.7
 	github.com/bradleyfalzon/ghinstallation/v2 v2.15.0
+	github.com/chzyer/readline v1.5.1
 	github.com/cloudevents/sdk-go/v2 v2.16.0
 	github.com/fvbommel/sortorder v1.1.0
 	github.com/gobwas/glob v0.2.3
@@ -129,7 +130,7 @@ require (
 	golang.org/x/crypto v0.37.0 // indirect
 	golang.org/x/net v0.39.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
-	golang.org/x/term v0.31.0 // indirect
+	golang.org/x/term v0.31.0
 	golang.org/x/time v0.11.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect
 	google.golang.org/api v0.231.0 // indirect

diff --git a/go.sum b/go.sum
@@ -88,8 +88,14 @@ github.com/cespare/xxhash/v2 v2.1.2/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XL
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
+github.com/chzyer/logex v1.2.1 h1:XHDu3E6q+gdHgsdTPH6ImJMIp436vR6MPtH8gP05QzM=
+github.com/chzyer/logex v1.2.1/go.mod h1:JLbx6lG2kDbNRFnfkgvh4eRJRPX1QCoOIWomwysCBrQ=
 github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
+github.com/chzyer/readline v1.5.1 h1:upd/6fQk4src78LMRzh5vItIt361/o4uq553V8B5sGI=
+github.com/chzyer/readline v1.5.1/go.mod h1:Eh+b79XXUwfKfcPLepksvw2tcLE/Ct21YObkaSkeBlk=
 github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
+github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
+github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cloudevents/sdk-go/observability/opencensus/v2 v2.15.2 h1:AbtPqiUDzKup5JpTZzO297/QXgL/TAdpdXQCNwLzlaM=
 github.com/cloudevents/sdk-go/observability/opencensus/v2 v2.15.2/go.mod h1:ZbYLE+yaEQ2j4vbRc9qzvGmg30A9LhwFt/1bSebNnbU=
@@ -675,6 +681,7 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220114195835-da31bd327af9/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220708085239-5a0f0661e09d/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

diff --git a/pkg/cel/cel.go b/pkg/cel/cel.go
@@ -55,12 +55,26 @@ func Value(query string, body any, headers, pacParams map[string]string, changed
 			decls.NewVariable("headers", mapStrDyn),
 			decls.NewVariable("pac", mapStrDyn),
 			decls.NewVariable("files", mapStrDyn),
+			// Direct variables as per documentation
+			decls.NewVariable("event", types.StringType),
+			decls.NewVariable("target_branch", types.StringType),
+			decls.NewVariable("source_branch", types.StringType),
+			decls.NewVariable("target_url", types.StringType),
+			decls.NewVariable("source_url", types.StringType),
+			decls.NewVariable("event_title", types.StringType),
 		))
 	val, err := evaluate(query, celDec, map[string]any{
 		"body":    jsonMap,
 		"pac":     pacParams,
 		"headers": headers,
 		"files":   changedFiles,
+		// Direct variables
+		"event":         pacParams["event"],
+		"target_branch": pacParams["target_branch"],
+		"source_branch": pacParams["source_branch"],
+		"target_url":    pacParams["target_url"],
+		"source_url":    pacParams["source_url"],
+		"event_title":   pacParams["event_title"],
 	})
 	if err != nil {
 		return nil, err