Add --instance flag to limactl shell so lima wrapper can forward flags

The `lima` helper script could not pass `limactl shell` flags (e.g. --sync,
--start) because it had no way to insert the instance name at the right
position among user-provided flags. Adding a hidden --instance flag lets
the wrapper simply do `limactl shell --instance $LIMA_INSTANCE "$@"`,
forwarding all flags without needing to enumerate them.

Fixes issue 4651

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>

cmd/lima

@@ -34,7 +34,7 @@ if [ "$#" -eq 1 ]; then
   fi
 fi
 
-set - "$LIMA_INSTANCE" "$@"
+set - --instance "$LIMA_INSTANCE" "$@"
 if [ -n "${LIMA_SHELL}" ]; then
   set - --shell "$LIMA_SHELL" "$@"
 fi

cmd/lima.bat

@@ -5,4 +5,4 @@ REM LIMACTL: Specifies the path to the limactl binary. Default is "limactl" in %
 
 IF NOT DEFINED LIMACTL (SET LIMACTL=limactl)
 IF NOT DEFINED LIMA_INSTANCE (SET LIMA_INSTANCE=default)
-%LIMACTL% shell %LIMA_INSTANCE% %*
+%LIMACTL% shell --instance %LIMA_INSTANCE% %*

cmd/limactl/shell.go

@@ -55,7 +55,7 @@ func newShellCommand() *cobra.Command {
 		SuggestFor:        []string{"ssh"},
 		Short:             "Execute shell in Lima",
 		Long:              shellHelp,
-		Args:              WrapArgsError(cobra.MinimumNArgs(1)),
+		Args:              WrapArgsError(cobra.ArbitraryArgs),
 		RunE:              shellAction,
 		ValidArgsFunction: shellBashComplete,
 		SilenceErrors:     true,
@@ -64,6 +64,8 @@ func newShellCommand() *cobra.Command {
 
 	shellCmd.Flags().SetInterspersed(false)
 
+	shellCmd.Flags().String("instance", "", "Instance name (used by the lima wrapper script)")
+	_ = shellCmd.Flags().MarkHidden("instance")
 	shellCmd.Flags().String("shell", "", "Shell interpreter, e.g. /bin/bash")
 	shellCmd.Flags().String("workdir", "", "Working directory")
 	shellCmd.Flags().Bool("reconnect", false, "Reconnect to the SSH session")
@@ -84,14 +86,29 @@ func shellAction(cmd *cobra.Command, args []string) error {
 	if err != nil {
 		return err
 	}
-	// simulate the behavior of double dash
-	newArg := []string{}
-	if len(args) >= 2 && args[1] == "--" {
-		newArg = append(newArg, args[:1]...)
-		newArg = append(newArg, args[2:]...)
-		args = newArg
+
+	// When --instance is specified, all positional args are treated as COMMAND.
+	// Otherwise, the first positional arg is the instance name (backward compatible).
+	instName, err := flags.GetString("instance")
+	if err != nil {
+		return err
+	}
+	if instName != "" {
+		// All args are COMMAND; prepend a placeholder instance name so the rest of the code works unchanged.
+		args = append([]string{instName}, args...)
+	} else {
+		if len(args) == 0 {
+			return errors.New("requires at least 1 arg(s), only received 0")
+		}
+		// simulate the behavior of double dash
+		newArg := []string{}
+		if len(args) >= 2 && args[1] == "--" {
+			newArg = append(newArg, args[:1]...)
+			newArg = append(newArg, args[2:]...)
+			args = newArg
+		}
+		instName = args[0]
 	}
-	instName := args[0]
 
 	if len(args) >= 2 {
 		switch args[1] {

hack/bats/tests/shell.bats

@@ -14,3 +14,60 @@ INSTANCE=bats-dummy
     # check that stdin is verified and not just crashing
     bash -c "yes | limactl shell --tty=true $INSTANCE true"
 }
+
+@test 'limactl shell without --instance requires positional arg' {
+    run_e -1 limactl shell --tty=false
+    assert_stderr --partial "requires at least 1 arg"
+}
+
+@test 'limactl shell nonexistent instance' {
+    run_e -1 limactl shell --tty=false nonexistent
+    assert_stderr --partial 'does not exist'
+}
+
+@test 'limactl shell --instance nonexistent instance' {
+    run_e -1 limactl shell --tty=false --instance nonexistent
+    assert_stderr --partial 'does not exist'
+}
+
+@test 'limactl shell --instance resolves instance name' {
+    # --instance should resolve the instance name the same way as the positional arg
+    run_e -1 limactl shell --tty=false --instance nonexistent
+    inst_output=$stderr
+
+    run_e -1 limactl shell --tty=false nonexistent
+    assert_stderr "$inst_output"
+}
+
+@test 'limactl shell --instance with unknown flag errors' {
+    # Without --, an unknown flag after --instance should be rejected by cobra
+    run_e -1 limactl shell --tty=false --instance "$INSTANCE" --nonexistent-flag
+    assert_stderr --partial "unknown flag"
+}
+
+@test 'limactl shell --instance with double dash stops flag parsing' {
+    # With --, "--nonexistent-flag" must be treated as a command, not a flag.
+    # The key assertion is that we do NOT get "unknown flag" (contrast with the test above).
+    run_e limactl shell --tty=false --instance "$INSTANCE" -- --nonexistent-flag </dev/null
+    refute_stderr --partial "unknown flag"
+}
+
+@test 'limactl shell positional instance with double dash' {
+    # Same double-dash behavior with positional instance name
+    run_e limactl shell --tty=false "$INSTANCE" -- --nonexistent-flag </dev/null
+    refute_stderr --partial "unknown flag"
+}
+
+@test 'lima wrapper forwards unknown limactl shell flags' {
+    # The lima wrapper should forward flags to limactl shell.
+    # --start=false is a valid limactl shell flag; if the wrapper didn't forward it,
+    # it would be treated as a command name and fail with "unknown flag".
+    run_e env LIMA_INSTANCE="$INSTANCE" lima --tty=false --start=false </dev/null
+    refute_stderr --partial "unknown flag"
+}
+
+@test 'lima wrapper rejects unknown flags' {
+    # Flags not recognized by limactl shell should cause an error
+    run_e -1 env LIMA_INSTANCE="$INSTANCE" lima --tty=false --nonexistent-flag
+    assert_stderr --partial "unknown flag"
+}