feat: add --params flag to kosli evaluate commands (#762)

## Summary

- Adds `--params` flag to `evaluate trail`, `evaluate trails`, and `evaluate input`, allowing policy authors to pass configuration data (thresholds, expected counts, etc.) without duplicating policy files
- Params are available in Rego policies as `data.params`, using OPA's idiomatic data document — existing policies that don't reference `data.params` are completely unaffected
- Accepts inline JSON (`--params '{"min_approvers": 2}'`) or file reference (`--params @params.json`)

## Motivation

Policies are currently fully static. Thresholds like "zero approvers" or "no critical vulnerabilities" are baked into the `.rego` file. If you want the same policy logic with different tolerances — say, 1 approver in staging, 2 in production — you need separate policy files duplicating the logic. That's the kind of duplication `kosli evaluate` is meant to eliminate.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tooky

TODO.md

@@ -47,3 +47,10 @@
   - [x] Refactor: use `cmd.InOrStdin()` for testable stdin
   - [x] Refactor: embed `commonEvaluateOptions` to remove flag duplication
 - [x] Slice 5: Detect terminal stdin and error when no input is piped
+
+## Add `--params` flag to `kosli evaluate` commands
+
+- [x] Slice 1: `evaluate.Evaluate()` accepts params, passes via OPA data store
+- [x] Slice 2: Add `--params` flag across all three commands
+- [x] Slice 3: Show params in `--show-input` output
+- [x] Slice 4: Update help text and examples

cmd/kosli/evaluate.go

@@ -18,7 +18,11 @@ Use ` + "`evaluate input`" + ` to evaluate a local JSON file or stdin without an
 
 The policy must use ` + "`package policy`" + ` and define an ` + "`allow`" + ` rule.
 An optional ` + "`violations`" + ` rule (a set of strings) can provide human-readable denial reasons.
-The command exits with code 0 when allowed and code 1 when denied.`
+The command exits with code 0 when allowed and code 1 when denied.
+
+Use ` + "`--params`" + ` to pass configuration data (thresholds, expected counts, etc.)
+to your policy. Params are available as ` + "`data.params`" + ` in Rego, keeping policy
+logic reusable across environments with different tolerances.`
 
 func newEvaluateCmd(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{

cmd/kosli/evaluateHelpers.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/url"
 	"os"
+	"strings"
 
 	"github.com/kosli-dev/cli/internal/evaluate"
 	"github.com/kosli-dev/cli/internal/output"
@@ -20,6 +21,7 @@ type commonEvaluateOptions struct {
 	output       string
 	showInput    bool
 	attestations []string
+	params       string
 }
 
 func (o *commonEvaluateOptions) addFlags(cmd *cobra.Command, policyDesc string) {
@@ -28,6 +30,7 @@ func (o *commonEvaluateOptions) addFlags(cmd *cobra.Command, policyDesc string)
 	cmd.Flags().StringVarP(&o.output, "output", "o", "table", outputFlag)
 	cmd.Flags().BoolVar(&o.showInput, "show-input", false, "[optional] Include the policy input data in the output.")
 	cmd.Flags().StringSliceVar(&o.attestations, "attestations", nil, "[optional] Limit which attestations are included. Plain name for trail-level, dot-qualified (artifact.name) for artifact-level.")
+	cmd.Flags().StringVar(&o.params, "params", "", "[optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params.")
 }
 
 func fetchAndEnrichTrail(flowName, trailName string, attestations []string) (interface{}, error) {
@@ -90,13 +93,36 @@ func fetchAndEnrichTrail(flowName, trailName string, attestations []string) (int
 	return trailData, nil
 }
 
-func evaluateAndPrintResult(out io.Writer, policyFile string, input map[string]interface{}, outputFormat string, showInput bool) error {
+func parseParams(raw string) (map[string]interface{}, error) {
+	if raw == "" {
+		return nil, nil
+	}
+
+	var jsonBytes []byte
+	if strings.HasPrefix(raw, "@") {
+		var err error
+		jsonBytes, err = os.ReadFile(raw[1:])
+		if err != nil {
+			return nil, fmt.Errorf("failed to read --params file: %w", err)
+		}
+	} else {
+		jsonBytes = []byte(raw)
+	}
+
+	var params map[string]interface{}
+	if err := json.Unmarshal(jsonBytes, &params); err != nil {
+		return nil, fmt.Errorf("failed to parse --params: %w", err)
+	}
+	return params, nil
+}
+
+func evaluateAndPrintResult(out io.Writer, policyFile string, input map[string]interface{}, outputFormat string, showInput bool, params map[string]interface{}) error {
 	policySource, err := os.ReadFile(policyFile)
 	if err != nil {
 		return fmt.Errorf("failed to read policy file: %w", err)
 	}
 
-	result, err := evaluate.Evaluate(string(policySource), input)
+	result, err := evaluate.Evaluate(string(policySource), input, params)
 	if err != nil {
 		return err
 	}
@@ -108,6 +134,9 @@ func evaluateAndPrintResult(out io.Writer, policyFile string, input map[string]i
 	if showInput {
 		auditResult["input"] = input
 	}
+	if showInput && params != nil {
+		auditResult["params"] = params
+	}
 
 	raw, err := json.Marshal(auditResult)
 	if err != nil {

cmd/kosli/evaluateInput.go

@@ -27,7 +27,10 @@ The policy must use ` + "`package policy`" + ` and define an ` + "`allow`" + ` r
 An optional ` + "`violations`" + ` rule (a set of strings) can provide human-readable denial reasons.
 The command exits with code 0 when allowed and code 1 when denied.
 
-When ` + "`--input-file`" + ` is omitted, JSON is read from stdin.`
+When ` + "`--input-file`" + ` is omitted, JSON is read from stdin.
+
+Use ` + "`--params`" + ` to pass configuration data to the policy as ` + "`data.params`" + `.
+This accepts inline JSON or a file reference (` + "`@file.json`" + `).`
 
 const evaluateInputExample = `
 # capture trail data for local policy iteration:
@@ -49,7 +52,19 @@ kosli evaluate input \
 
 # read input from stdin:
 cat trail-data.json | kosli evaluate input \
-	--policy policy.rego`
+	--policy policy.rego
+
+# evaluate with policy parameters (inline JSON):
+kosli evaluate input \
+	--input-file trail-data.json \
+	--policy policy.rego \
+	--params '{"threshold": 3}'
+
+# evaluate with policy parameters from a file:
+kosli evaluate input \
+	--input-file trail-data.json \
+	--policy policy.rego \
+	--params @params.json`
 
 func newEvaluateInputCmd(out io.Writer) *cobra.Command {
 	o := new(evaluateInputOptions)
@@ -94,7 +109,12 @@ func (o *evaluateInputOptions) run(out io.Writer, in io.Reader) error {
 		return err
 	}
 
-	return evaluateAndPrintResult(out, o.policyFile, input, o.output, o.showInput)
+	params, err := parseParams(o.params)
+	if err != nil {
+		return err
+	}
+
+	return evaluateAndPrintResult(out, o.policyFile, input, o.output, o.showInput, params)
 }
 
 func loadInputFromFile(filePath string) (result map[string]interface{}, err error) {

cmd/kosli/evaluateInput_test.go

@@ -82,6 +82,31 @@ func (suite *EvaluateInputCommandTestSuite) TestEvaluateInputCmd() {
 				{"input.trail.name", "test-trail"},
 			},
 		},
+		{
+			name:        "inline --params overrides policy default threshold",
+			cmd:         `evaluate input --input-file testdata/evaluate/score-input.json --policy testdata/policies/check-params-threshold.rego --params '{"threshold":3}'`,
+			goldenRegex: `RESULT:\s+ALLOWED`,
+		},
+		{
+			name:        "--params from file overrides policy default threshold",
+			cmd:         "evaluate input --input-file testdata/evaluate/score-input.json --policy testdata/policies/check-params-threshold.rego --params @testdata/evaluate/params-low-threshold.json",
+			goldenRegex: `RESULT:\s+ALLOWED`,
+		},
+		{
+			wantError:   true,
+			name:        "--params with invalid JSON returns error",
+			cmd:         "evaluate input --input-file testdata/evaluate/score-input.json --policy testdata/policies/allow-all.rego --params not-json",
+			goldenRegex: `failed to parse --params`,
+		},
+		{
+			name: "show-input with params includes params in JSON output",
+			cmd:  `evaluate input --input-file testdata/evaluate/score-input.json --policy testdata/policies/check-params-threshold.rego --params '{"threshold":3}' --output json --show-input`,
+			goldenJson: []jsonCheck{
+				{"allow", true},
+				{"input.score", float64(5)},
+				{"params.threshold", float64(3)},
+			},
+		},
 	}
 	runTestCmd(suite.T(), tests)
 }

cmd/kosli/evaluateTrail.go

@@ -39,6 +39,22 @@ kosli evaluate trail yourTrailName \
 	--show-input \
 	--output json \
 	--api-token yourAPIToken \
+	--org yourOrgName
+
+# evaluate a trail with policy parameters (inline JSON):
+kosli evaluate trail yourTrailName \
+	--policy yourPolicyFile.rego \
+	--flow yourFlowName \
+	--params '{"min_approvers": 2}' \
+	--api-token yourAPIToken \
+	--org yourOrgName
+
+# evaluate a trail with policy parameters from a file:
+kosli evaluate trail yourTrailName \
+	--policy yourPolicyFile.rego \
+	--flow yourFlowName \
+	--params @params.json \
+	--api-token yourAPIToken \
 	--org yourOrgName`
 
 type evaluateTrailOptions struct {
@@ -81,9 +97,14 @@ func (o *evaluateTrailOptions) run(out io.Writer, args []string) error {
 		return err
 	}
 
+	params, err := parseParams(o.params)
+	if err != nil {
+		return err
+	}
+
 	input := map[string]interface{}{
 		"trail": trailData,
 	}
 
-	return evaluateAndPrintResult(out, o.policyFile, input, o.output, o.showInput)
+	return evaluateAndPrintResult(out, o.policyFile, input, o.output, o.showInput, params)
 }

cmd/kosli/evaluateTrails.go

@@ -40,6 +40,14 @@ kosli evaluate trails yourTrailName1 yourTrailName2 \
 	--show-input \
 	--output json \
 	--api-token yourAPIToken \
+	--org yourOrgName
+
+# evaluate trails with policy parameters:
+kosli evaluate trails yourTrailName1 yourTrailName2 \
+	--policy yourPolicyFile.rego \
+	--flow yourFlowName \
+	--params '{"min_approvers": 2}' \
+	--api-token yourAPIToken \
 	--org yourOrgName`
 
 type evaluateTrailsOptions struct {
@@ -86,9 +94,14 @@ func (o *evaluateTrailsOptions) run(out io.Writer, args []string) error {
 		trails = append(trails, trailData)
 	}
 
+	params, err := parseParams(o.params)
+	if err != nil {
+		return err
+	}
+
 	input := map[string]interface{}{
 		"trails": trails,
 	}
 
-	return evaluateAndPrintResult(out, o.policyFile, input, o.output, o.showInput)
+	return evaluateAndPrintResult(out, o.policyFile, input, o.output, o.showInput, params)
 }

cmd/kosli/testdata/evaluate/params-low-threshold.json

@@ -0,0 +1 @@
+{"threshold": 3}

cmd/kosli/testdata/evaluate/score-input.json

@@ -0,0 +1 @@
+{"score": 5}

cmd/kosli/testdata/policies/check-params-threshold.rego

@@ -0,0 +1,16 @@
+package policy
+
+import rego.v1
+
+default allow := false
+
+default threshold := 10
+
+threshold := data.params.threshold if { data.params.threshold }
+
+allow if { input.score >= threshold }
+
+violations contains msg if {
+	input.score < threshold
+	msg := sprintf("score %d is below threshold %d", [input.score, threshold])
+}