limactl: add --param shortcut for template parameters

Add a --param NAME=VALUE option to the shared edit flag handling used by limactl create, start, edit, clone, and rename. The option expands to the equivalent yq update for .param.NAME, so users can write --param release=v1.35 instead of --set '.param.release="v1.35"'.

Reject params that are not already defined by the template/config, so typos fail before modifying the YAML.

Add unit coverage for expression generation and BATS coverage for create and edit CLI behavior.

Signed-off-by: Jan Dubois <jan.dubois@suse.com>

Author: jandubois

cmd/limactl/clone.go

@@ -77,7 +77,7 @@ func cloneOrRenameAction(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	yqExprs, err := editflags.YQExpressions(flags, false)
+	yqExprs, err := editflags.YQExpressions(flags, false, newInst.Config.Param)
 	if err != nil {
 		return err
 	}

cmd/limactl/edit.go

@@ -85,7 +85,15 @@ func editAction(cmd *cobra.Command, args []string) error {
 	if err != nil {
 		return err
 	}
-	yqExprs, err := editflags.YQExpressions(flags, false)
+	var params map[string]string
+	if flags.Changed("param") {
+		var y limatype.LimaYAML
+		if err := limayaml.Unmarshal(yContent, &y, filePath); err != nil {
+			return err
+		}
+		params = y.Param
+	}
+	yqExprs, err := editflags.YQExpressions(flags, false, params)
 	if err != nil {
 		return err
 	}

cmd/limactl/editflags/editflags.go

@@ -69,6 +69,7 @@ func RegisterEdit(cmd *cobra.Command, commentPrefix string) {
 	flags.Bool("rosetta", false, commentPrefix+"Enable Rosetta (for vz instances)")
 
 	flags.StringArray("set", []string{}, commentPrefix+"Modify the template inplace, using yq syntax. Can be passed multiple times.")
+	flags.StringArray("param", []string{}, commentPrefix+"Set a template parameter, e.g. name=value. Can be passed multiple times.")
 
 	flags.Uint16("ssh-port", 0, commentPrefix+"SSH port (0 for random)") // colima-compatible
 	_ = cmd.RegisterFlagCompletionFunc("ssh-port", func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
@@ -169,6 +170,21 @@ func BuildPortForwardExpression(portForwards []string) (string, error) {
 	return expr, nil
 }
 
+func BuildParamExpressions(params []string, allowedParams map[string]string) ([]string, error) {
+	exprs := make([]string, len(params))
+	for i, param := range params {
+		key, value, ok := strings.Cut(param, "=")
+		if !ok {
+			return nil, fmt.Errorf("invalid parameter %q, expected NAME=VALUE", param)
+		}
+		if _, ok := allowedParams[key]; !ok {
+			return nil, fmt.Errorf("template does not define param %q", key)
+		}
+		exprs[i] = fmt.Sprintf(".param[%q] = %q", key, value)
+	}
+	return exprs, nil
+}
+
 func buildMountListExpression(ss []string) (string, error) {
 	mounts := make([]string, len(ss))
 	for i, s := range ss {
@@ -184,7 +200,7 @@ func buildMountListExpression(ss []string) (string, error) {
 }
 
 // YQExpressions returns YQ expressions.
-func YQExpressions(flags *flag.FlagSet, newInstance bool) ([]string, error) {
+func YQExpressions(flags *flag.FlagSet, newInstance bool, params map[string]string) ([]string, error) {
 	type def struct {
 		flagName                 string
 		exprFunc                 func(*flag.Flag) ([]string, error)
@@ -335,6 +351,13 @@ func YQExpressions(flags *flag.FlagSet, newInstance bool) ([]string, error) {
 		{"set", func(v *flag.Flag) ([]string, error) {
 			return v.Value.(flag.SliceValue).GetSlice(), nil
 		}, false, false},
+		{"param", func(_ *flag.Flag) ([]string, error) {
+			ss, err := flags.GetStringArray("param")
+			if err != nil {
+				return nil, err
+			}
+			return BuildParamExpressions(ss, params)
+		}, false, false},
 		{
 			"video",
 			func(_ *flag.Flag) ([]string, error) {

cmd/limactl/editflags/editflags_test.go

@@ -162,6 +162,53 @@ func TestParsePortForward(t *testing.T) {
 	}
 }
 
+func TestBuildParamExpressions(t *testing.T) {
+	tests := []struct {
+		name          string
+		params        []string
+		allowedParams map[string]string
+		expected      []string
+		expectError   string
+	}{
+		{
+			name:          "single param",
+			params:        []string{"version=v1.35"},
+			allowedParams: map[string]string{"version": ""},
+			expected:      []string{`.param["version"] = "v1.35"`},
+		},
+		{
+			name:          "value contains equals",
+			params:        []string{"token=a=b"},
+			allowedParams: map[string]string{"token": ""},
+			expected:      []string{`.param["token"] = "a=b"`},
+		},
+		{
+			name:          "invalid format",
+			params:        []string{"version"},
+			allowedParams: map[string]string{"version": ""},
+			expectError:   `invalid parameter "version", expected NAME=VALUE`,
+		},
+		{
+			name:          "undefined param",
+			params:        []string{"missing=value"},
+			allowedParams: map[string]string{"version": ""},
+			expectError:   `template does not define param "missing"`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := BuildParamExpressions(tt.params, tt.allowedParams)
+			if tt.expectError != "" {
+				assert.ErrorContains(t, err, tt.expectError)
+			} else {
+				assert.NilError(t, err)
+				assert.DeepEqual(t, tt.expected, result)
+			}
+		})
+	}
+}
+
 func TestYQExpressions(t *testing.T) {
 	expand := func(s string) string {
 		s, err := localpathutil.Expand(s)
@@ -225,6 +272,18 @@ func TestYQExpressions(t *testing.T) {
 			newInstance: false,
 			expected:    []string{`.nestedVirtualization = true`},
 		},
+		{
+			name:        "param",
+			args:        []string{"--param", "version=v1.35"},
+			newInstance: false,
+			expected:    []string{`.param["version"] = "v1.35"`},
+		},
+		{
+			name:        "undefined param",
+			args:        []string{"--param", "missing=value"},
+			newInstance: false,
+			expectError: `template does not define param "missing"`,
+		},
 		{
 			name:        "invalid network",
 			args:        []string{"--network", "invalid"},
@@ -237,7 +296,7 @@ func TestYQExpressions(t *testing.T) {
 			cmd := &cobra.Command{}
 			RegisterEdit(cmd, "")
 			assert.NilError(t, cmd.ParseFlags(tt.args))
-			expr, err := YQExpressions(cmd.Flags(), tt.newInstance)
+			expr, err := YQExpressions(cmd.Flags(), tt.newInstance, map[string]string{"version": ""})
 			if tt.expectError != "" {
 				assert.ErrorContains(t, err, tt.expectError)
 			} else {

cmd/limactl/start.go

@@ -58,6 +58,9 @@ func newCreateCommand() *cobra.Command {
   To create an instance "default" with yq expressions:
   $ limactl create --set='.cpus = 2 | .memory = "2GiB"'
 
+  To create an instance "default" with a template parameter:
+  $ limactl create --name=default --param containerdSnapshotter=false template:docker
+
   To see the template list:
   $ limactl create --list-templates
 
@@ -282,7 +285,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 				return nil, fmt.Errorf("instance %q already exists", tmpl.Name)
 			}
 			logrus.Infof("Using the existing instance %q", tmpl.Name)
-			yqExprs, err := editflags.YQExpressions(flags, false)
+			yqExprs, err := editflags.YQExpressions(flags, false, inst.Config.Param)
 			if err != nil {
 				return nil, err
 			}
@@ -331,7 +334,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 	if tmpl.Config != nil && tmpl.Config.OS != nil && *tmpl.Config.OS != limatype.LINUX {
 		logrus.Warn("Support for non-Linux guests is experimental")
 	}
-	yqExprs, err := editflags.YQExpressions(flags, true)
+	yqExprs, err := editflags.YQExpressions(flags, true, tmpl.Config.Param)
 	if err != nil {
 		return nil, err
 	}

hack/bats/tests/param.bats

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: Copyright The Lima Authors
+# SPDX-License-Identifier: Apache-2.0
+
+load "../helpers/load"
+
+LOCAL_LIMA_HOME="${LIMA_HOME:?}/_bats_param"
+
+local_setup_file() {
+    export LIMA_HOME="${LOCAL_LIMA_HOME:?}"
+    rm -rf "${LOCAL_LIMA_HOME:?}"
+}
+
+local_setup() {
+    export LIMA_HOME="${LOCAL_LIMA_HOME:?}"
+}
+
+param_template() {
+    cat <<'EOF'
+images:
+- location: /etc/profile
+plain: true
+param:
+  release: ""
+provision:
+- mode: system
+  script: |
+    echo "$PARAM_release"
+EOF
+}
+
+@test 'create accepts --param shortcut' {
+    run -0 limactl create --name param-create --param=release=v1.35 - <<<"$(param_template)"
+
+    run -0 limactl yq -r .param.release <"${LIMA_HOME}/param-create/lima.yaml"
+    assert_output "v1.35"
+}
+
+@test 'create rejects undefined --param' {
+    run_e -1 limactl create --name param-create-invalid --param missing=value - <<<"$(param_template)"
+    assert_fatal 'error while processing flag "param": template does not define param "missing"'
+}
+
+@test 'edit accepts --param shortcut' {
+    run -0 limactl create --name param-edit - <<<"$(param_template)"
+
+    run -0 limactl edit --param release=v1.36 param-edit
+
+    run -0 limactl yq -r .param.release <"${LIMA_HOME}/param-edit/lima.yaml"
+    assert_output "v1.36"
+}