limactl: add limactl create command

AkihiroSuda · AkihiroSuda · commit 65f0000048ea · 2023-06-27T15:16:52.000+09:00
`limactl create` is similar to `limactl start` but it does not start the
created instance, and it does not accept an existing instance name as an argument.

Now it is discouraged (not deprecated) to use `limactl start` for
creating new instances.

Discouraged form:
```
limactl start --name=foo template://docker
```

Recommended form:
```
limactl create --name=foo template://docker
limactl start foo
```

Signed-off-by: Akihiro Suda &lt;akihiro.suda.cz@hco.ntt.co.jp&gt;
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -77,6 +77,7 @@ jobs:
 
         ## Usage
         \`\`\`console
+        [macOS]$ limactl create
         [macOS]$ limactl start
         ...
         INFO[0029] READY. Run \`lima\` to open the shell.
diff --git a/cmd/apptainer.lima b/cmd/apptainer.lima
@@ -3,7 +3,7 @@ set -eu
 : "${LIMA_INSTANCE:=apptainer}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl start --name=$LIMA_INSTANCE template://apptainer\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://apptainer\` to create a new instance" >&2
   exit 1
 fi
 export LIMA_INSTANCE
diff --git a/cmd/docker.lima b/cmd/docker.lima
@@ -4,7 +4,7 @@ set -eu
 : "${DOCKER:=docker}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl start --name=$LIMA_INSTANCE template://docker\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://docker\` to create a new instance" >&2
   exit 1
 fi
 DOCKER=$(command -v "$DOCKER" || true)
diff --git a/cmd/kubectl.lima b/cmd/kubectl.lima
@@ -9,14 +9,14 @@ if [ -z "$LIMA_INSTANCE" ]; then
   elif [ "$(limactl ls -f '{{.Status}}' k8s 2>/dev/null)" = "Running" ]; then
     LIMA_INSTANCE=k8s
   else
-    echo "No k3s or k8s running instances found. Either start one with" >&2
-    echo "limactl start --name=k3s template://k3s" >&2
-    echo "limactl start --name=k8s template://k8s" >&2
+    echo "No k3s or k8s running instances found. Either create one with" >&2
+    echo "limactl create --name=k3s template://k3s" >&2
+    echo "limactl create --name=k8s template://k8s" >&2
     echo "or set LIMA_INSTANCE to the name of your Kubernetes instance" >&2
     exit 1
   fi
 elif [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl start --name=$LIMA_INSTANCE\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE\` to create a new instance" >&2
   exit 1
 fi
 KUBECTL=$(command -v "$KUBECTL" || true)
diff --git a/cmd/limactl/completion.go b/cmd/limactl/completion.go
@@ -2,6 +2,7 @@ package main
 
 import (
 	"github.com/lima-vm/lima/pkg/store"
+	"github.com/lima-vm/lima/pkg/templatestore"
 	"github.com/spf13/cobra"
 )
 
@@ -12,3 +13,13 @@ func bashCompleteInstanceNames(_ *cobra.Command) ([]string, cobra.ShellCompDirec
 	}
 	return instances, cobra.ShellCompDirectiveNoFileComp
 }
+
+func bashCompleteTemplateNames(_ *cobra.Command) ([]string, cobra.ShellCompDirective) {
+	var comp []string
+	if templates, err := templatestore.Templates(); err == nil {
+		for _, f := range templates {
+			comp = append(comp, "template://"+f.Name)
+		}
+	}
+	return comp, cobra.ShellCompDirectiveDefault
+}
diff --git a/cmd/limactl/copy.go b/cmd/limactl/copy.go
@@ -78,7 +78,7 @@ func copyAction(cmd *cobra.Command, args []string) error {
 			inst, err := store.Inspect(instName)
 			if err != nil {
 				if errors.Is(err, os.ErrNotExist) {
-					return fmt.Errorf("instance %q does not exist, run `limactl start %s` to create a new instance", instName, instName)
+					return fmt.Errorf("instance %q does not exist, run `limactl create %s` to create a new instance", instName, instName)
 				}
 				return err
 			}
diff --git a/cmd/limactl/list.go b/cmd/limactl/list.go
@@ -119,7 +119,7 @@ func listAction(cmd *cobra.Command, args []string) error {
 		return err
 	}
 	if len(allinstances) == 0 {
-		logrus.Warn("No instance found. Run `limactl start` to create an instance.")
+		logrus.Warn("No instance found. Run `limactl create` to create an instance.")
 		return nil
 	}
 
diff --git a/cmd/limactl/main.go b/cmd/limactl/main.go
@@ -94,6 +94,7 @@ func newApp() *cobra.Command {
 		return nil
 	}
 	rootCmd.AddCommand(
+		newCreateCommand(),
 		newStartCommand(),
 		newStopCommand(),
 		newShellCommand(),
diff --git a/cmd/limactl/shell.go b/cmd/limactl/shell.go
@@ -61,7 +61,7 @@ func shellAction(cmd *cobra.Command, args []string) error {
 
 	if len(args) >= 2 {
 		switch args[1] {
-		case "start", "delete", "shell":
+		case "create", "start", "delete", "shell":
 			// `lima start` (alias of `limactl $LIMA_INSTANCE start`) is probably a typo of `limactl start`
 			logrus.Warnf("Perhaps you meant `limactl %s`?", strings.Join(args[1:], " "))
 		}
@@ -70,7 +70,7 @@ func shellAction(cmd *cobra.Command, args []string) error {
 	inst, err := store.Inspect(instName)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
-			return fmt.Errorf("instance %q does not exist, run `limactl start %s` to create a new instance", instName, instName)
+			return fmt.Errorf("instance %q does not exist, run `limactl create %s` to create a new instance", instName, instName)
 		}
 		return err
 	}
diff --git a/cmd/limactl/show_ssh.go b/cmd/limactl/show_ssh.go
@@ -68,7 +68,7 @@ func showSSHAction(cmd *cobra.Command, args []string) error {
 	inst, err := store.Inspect(instName)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
-			return fmt.Errorf("instance %q does not exist, run `limactl start %s` to create a new instance", instName, instName)
+			return fmt.Errorf("instance %q does not exist, run `limactl create %s` to create a new instance", instName, instName)
 		}
 		return err
 	}
diff --git a/cmd/limactl/start.go b/cmd/limactl/start.go
@@ -27,46 +27,73 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func newStartCommand() *cobra.Command {
-	var startCommand = &cobra.Command{
-		Use: "start NAME|FILE.yaml|URL",
+func registerCreateFlags(cmd *cobra.Command, commentPrefix string) {
+	flags := cmd.Flags()
+	// TODO: "survey" does not support using cygwin terminal on windows yet
+	flags.Bool("tty", isatty.IsTerminal(os.Stdout.Fd()), commentPrefix+"enable TUI interactions such as opening an editor, defaults to true when stdout is a terminal")
+	flags.String("name", "", commentPrefix+"override the instance name")
+	flags.String("set", "", commentPrefix+"modify the template inplace, using yq syntax")
+	flags.Bool("list-templates", false, commentPrefix+"list available templates and exit")
+}
+
+func newCreateCommand() *cobra.Command {
+	var createCommand = &cobra.Command{
+		Use: "create FILE.yaml|URL",
 		Example: `
-To create an instance "default" (if not created yet) from the default Ubuntu template, and start it:
-$ limactl start
+To create an instance "default" from the default Ubuntu template:
+$ limactl create
 
 To create an instance "default" from a template "docker":
-$ limactl start --name=default template://docker
+$ limactl create --name=default template://docker
 
 To create an instance "default" with modified parameters:
-$ limactl start --set='.cpus = 2 | .memory = "2GiB"'
+$ limactl create --set='.cpus = 2 | .memory = "2GiB"'
 
 To see the template list:
-$ limactl start --list-templates
+$ limactl create --list-templates
 
 To create an instance "default" from a local file:
-$ limactl start --name=default /usr/local/share/lima/examples/fedora.yaml
+$ limactl create --name=default /usr/local/share/lima/examples/fedora.yaml
 
 To create an instance "default" from a remote URL (use carefully, with a trustable source):
-$ limactl start --name=default https://raw.githubusercontent.com/lima-vm/lima/master/examples/alpine.yaml
+$ limactl create --name=default https://raw.githubusercontent.com/lima-vm/lima/master/examples/alpine.yaml
 
 To create an instance "local" from a template passed to stdin (--name parameter is required):
-$ cat template.yaml | limactl start --name=local -
+$ cat template.yaml | limactl create --name=local -
+`,
+		Short:             "Create an instance of Lima",
+		Args:              WrapArgsError(cobra.MaximumNArgs(1)),
+		ValidArgsFunction: createBashComplete,
+		RunE:              createAction,
+	}
+	registerCreateFlags(createCommand, "")
+	return createCommand
+}
+
+func newStartCommand() *cobra.Command {
+	var startCommand = &cobra.Command{
+		Use: "start NAME|FILE.yaml|URL",
+		Example: `
+To create an instance "default" (if not created yet) from the default Ubuntu template, and start it:
+$ limactl start
+
+To create an instance "default" from a template "docker", and start it:
+$ limactl start --name=default template://docker
+
+'limactl start' also accepts the 'limactl create' flags such as '--set'.
+See the examples in 'limactl create --help'.
 `,
 		Short:             "Start an instance of Lima",
 		Args:              WrapArgsError(cobra.MaximumNArgs(1)),
 		ValidArgsFunction: startBashComplete,
 		RunE:              startAction,
 	}
-	// TODO: "survey" does not support using cygwin terminal on windows yet
-	startCommand.Flags().Bool("tty", isatty.IsTerminal(os.Stdout.Fd()), "enable TUI interactions such as opening an editor, defaults to true when stdout is a terminal")
-	startCommand.Flags().String("name", "", "override the instance name")
-	startCommand.Flags().String("set", "", "modify the template inplace, using yq syntax")
-	startCommand.Flags().Bool("list-templates", false, "list available templates and exit")
+	registerCreateFlags(startCommand, "[limactl create] ")
 	startCommand.Flags().Duration("timeout", start.DefaultWatchHostAgentEventsTimeout, "duration to wait for the instance to be running before timing out")
 	return startCommand
 }
 
-func loadOrCreateInstance(cmd *cobra.Command, args []string) (*store.Instance, error) {
+func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*store.Instance, error) {
 	var arg string // can be empty
 	if len(args) > 0 {
 		arg = args[0]
@@ -187,9 +214,12 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string) (*store.Instance, e
 		}
 		inst, err := store.Inspect(st.instName)
 		if err == nil {
+			if createOnly {
+				return nil, fmt.Errorf("Instance %q already exists", st.instName)
+			}
 			logrus.Infof("Using the existing instance %q", st.instName)
 			if arg == "" {
-				logrus.Infof("Hint: To create another instance, run the following command: limactl start --name=NAME template://default")
+				logrus.Infof("Hint: To create another instance, run the following command: limactl create --name=NAME template://default")
 			}
 			return inst, nil
 		}
@@ -198,7 +228,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string) (*store.Instance, e
 		}
 		if arg != "" && arg != DefaultInstanceName {
 			logrus.Infof("Creating an instance %q from template://default (Not from template://%s)", st.instName, st.instName)
-			logrus.Warnf("This form is deprecated. Use `limactl start --name=%s template://default` instead", st.instName)
+			logrus.Warnf("This form is deprecated. Use `limactl create --name=%s template://default` instead", st.instName)
 		}
 		// Read the default template for creating a new instance
 		st.yBytes, err = templatestore.Read(templatestore.Default)
@@ -369,20 +399,46 @@ func chooseNextCreatorState(st *creatorState) (*creatorState, error) {
 	}
 }
 
-func startAction(cmd *cobra.Command, args []string) error {
+// createStartActionCommon is shared by createAction and startAction.
+func createStartActionCommon(cmd *cobra.Command, _ []string) (exit bool, err error) {
 	if listTemplates, err := cmd.Flags().GetBool("list-templates"); err != nil {
-		return err
+		return true, err
 	} else if listTemplates {
 		if templates, err := templatestore.Templates(); err == nil {
 			w := cmd.OutOrStdout()
 			for _, f := range templates {
 				fmt.Fprintln(w, f.Name)
 			}
-			return nil
+			return true, nil
 		}
 	}
+	return false, nil
+}
+
+func createAction(cmd *cobra.Command, args []string) error {
+	if exit, err := createStartActionCommon(cmd, args); err != nil {
+		return err
+	} else if exit {
+		return nil
+	}
+	inst, err := loadOrCreateInstance(cmd, args, true)
+	if err != nil {
+		return err
+	}
+	if len(inst.Errors) > 0 {
+		return fmt.Errorf("errors inspecting instance: %+v", inst.Errors)
+	}
+	logrus.Infof("Run `limactl start %q` to start the instance.", inst.Name)
+	return nil
+}
 
-	inst, err := loadOrCreateInstance(cmd, args)
+func startAction(cmd *cobra.Command, args []string) error {
+	if exit, err := createStartActionCommon(cmd, args); err != nil {
+		return err
+	} else if exit {
+		return nil
+	}
+	inst, err := loadOrCreateInstance(cmd, args, false)
 	if err != nil {
 		return err
 	}
@@ -417,12 +473,12 @@ func startAction(cmd *cobra.Command, args []string) error {
 	return start.Start(ctx, inst)
 }
 
+func createBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return bashCompleteTemplateNames(cmd)
+}
+
 func startBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-	comp, _ := bashCompleteInstanceNames(cmd)
-	if templates, err := templatestore.Templates(); err == nil {
-		for _, f := range templates {
-			comp = append(comp, "template://"+f.Name)
-		}
-	}
-	return comp, cobra.ShellCompDirectiveDefault
+	compInst, _ := bashCompleteInstanceNames(cmd)
+	compTmpl, _ := bashCompleteTemplateNames(cmd)
+	return append(compInst, compTmpl...), cobra.ShellCompDirectiveDefault
 }
diff --git a/cmd/podman.lima b/cmd/podman.lima
@@ -4,7 +4,7 @@ set -eu
 : "${PODMAN:=podman}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl start --name=$LIMA_INSTANCE template://podman\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://podman\` to create a new instance" >&2
   exit 1
 fi
 PODMAN=$(command -v "$PODMAN" || true)
diff --git a/hack/test-example.sh b/hack/test-example.sh
@@ -18,8 +18,7 @@ limactl validate "$FILE"
 
 # --cpus=1 is needed for running vz on GHA: https://github.com/lima-vm/lima/pull/1511#issuecomment-1574937888
 LIMACTL_CREATE_SET='.cpus = 1 | .memory="1GiB"'
-# TODO: add "limactl create" command
-LIMACTL_CREATE_AND_START=(limactl start --tty=false --set="${LIMACTL_CREATE_SET}")
+LIMACTL_CREATE=(limactl create --tty=false --set="${LIMACTL_CREATE_SET}")
 
 declare -A CHECKS=(
 	["systemd"]="1"
@@ -103,7 +102,7 @@ function diagnose() {
 
 export ftp_proxy=http://localhost:2121
 
-INFO "Starting \"$NAME\" from \"$FILE\""
+INFO "Creating \"$NAME\" from \"$FILE\""
 defer "limactl delete -f \"$NAME\""
 
 if [[ -n ${CHECKS["disk"]} ]]; then
@@ -114,7 +113,12 @@ if [[ -n ${CHECKS["disk"]} ]]; then
 fi
 
 set -x
-if ! "${LIMACTL_CREATE_AND_START[@]}" "$FILE"; then
+"${LIMACTL_CREATE[@]}" "$FILE"
+set +x
+
+INFO "Starting \"$NAME\""
+set -x
+if ! limactl start "$NAME"; then
 	ERROR "Failed to start \"$NAME\""
 	diagnose "$NAME"
 	exit 1
@@ -329,7 +333,8 @@ fi
 if [[ -n ${CHECKS["user-v2"]} ]]; then
 	INFO "Testing user-v2 network"
 	secondvm="$NAME-1"
-	"${LIMACTL_CREATE_AND_START[@]}" "$FILE" --name "$secondvm"
+	"${LIMACTL_CREATE[@]}" "$FILE" --name "$secondvm"
+	limactl start "$secondvm"
 	guestNewip="$(limactl shell "$secondvm" ip -4 -j addr show dev eth0 | jq -r '.[0].addr_info[0].local')"
 	INFO "IP of $secondvm is $guestNewip"
 	set -x

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ package main`
`2`	`2`
`3`	`3`	`import (`
`4`	`4`	`"github.com/lima-vm/lima/pkg/store"`
	`5`	`+ "github.com/lima-vm/lima/pkg/templatestore"`
`5`	`6`	`"github.com/spf13/cobra"`
`6`	`7`	`)`
`7`	`8`
`@@ -12,3 +13,13 @@ func bashCompleteInstanceNames(_ *cobra.Command) ([]string, cobra.ShellCompDirec`
`12`	`13`	`}`
`13`	`14`	`return instances, cobra.ShellCompDirectiveNoFileComp`
`14`	`15`	`}`
	`16`	`+`
	`17`	`+func bashCompleteTemplateNames(_ *cobra.Command) ([]string, cobra.ShellCompDirective) {`
	`18`	`+ var comp []string`
	`19`	`+ if templates, err := templatestore.Templates(); err == nil {`
	`20`	`+ for _, f := range templates {`
	`21`	`+ comp = append(comp, "template://"+f.Name)`
	`22`	`+ }`
	`23`	`+ }`
	`24`	`+ return comp, cobra.ShellCompDirectiveDefault`
	`25`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ func copyAction(cmd *cobra.Command, args []string) error {`
`78`	`78`	`inst, err := store.Inspect(instName)`
`79`	`79`	`if err != nil {`
`80`	`80`	`if errors.Is(err, os.ErrNotExist) {`
`81`		- return fmt.Errorf("instance %q does not exist, run `limactl start %s` to create a new instance", instName, instName)
	`81`	+ return fmt.Errorf("instance %q does not exist, run `limactl create %s` to create a new instance", instName, instName)
`82`	`82`	`}`
`83`	`83`	`return err`
`84`	`84`	`}`
Original file line number	Diff line number	Diff line change
`@@ -119,7 +119,7 @@ func listAction(cmd *cobra.Command, args []string) error {`
`119`	`119`	`return err`
`120`	`120`	`}`
`121`	`121`	`if len(allinstances) == 0 {`
`122`		- logrus.Warn("No instance found. Run `limactl start` to create an instance.")
	`122`	+ logrus.Warn("No instance found. Run `limactl create` to create an instance.")
`123`	`123`	`return nil`
`124`	`124`	`}`
`125`	`125`
Original file line number	Diff line number	Diff line change
`@@ -94,6 +94,7 @@ func newApp() *cobra.Command {`
`94`	`94`	`return nil`
`95`	`95`	`}`
`96`	`96`	`rootCmd.AddCommand(`
	`97`	`+ newCreateCommand(),`
`97`	`98`	`newStartCommand(),`
`98`	`99`	`newStopCommand(),`
`99`	`100`	`newShellCommand(),`
Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ func shellAction(cmd *cobra.Command, args []string) error {`
`61`	`61`
`62`	`62`	`if len(args) >= 2 {`
`63`	`63`	`switch args[1] {`
`64`		`- case "start", "delete", "shell":`
	`64`	`+ case "create", "start", "delete", "shell":`
`65`	`65`	// `lima start` (alias of `limactl $LIMA_INSTANCE start`) is probably a typo of `limactl start`
`66`	`66`	logrus.Warnf("Perhaps you meant `limactl %s`?", strings.Join(args[1:], " "))
`67`	`67`	`}`
`@@ -70,7 +70,7 @@ func shellAction(cmd *cobra.Command, args []string) error {`
`70`	`70`	`inst, err := store.Inspect(instName)`
`71`	`71`	`if err != nil {`
`72`	`72`	`if errors.Is(err, os.ErrNotExist) {`
`73`		- return fmt.Errorf("instance %q does not exist, run `limactl start %s` to create a new instance", instName, instName)
	`73`	+ return fmt.Errorf("instance %q does not exist, run `limactl create %s` to create a new instance", instName, instName)
`74`	`74`	`}`
`75`	`75`	`return err`
`76`	`76`	`}`
Original file line number	Diff line number	Diff line change
`@@ -68,7 +68,7 @@ func showSSHAction(cmd *cobra.Command, args []string) error {`
`68`	`68`	`inst, err := store.Inspect(instName)`
`69`	`69`	`if err != nil {`
`70`	`70`	`if errors.Is(err, os.ErrNotExist) {`
`71`		- return fmt.Errorf("instance %q does not exist, run `limactl start %s` to create a new instance", instName, instName)
	`71`	+ return fmt.Errorf("instance %q does not exist, run `limactl create %s` to create a new instance", instName, instName)
`72`	`72`	`}`
`73`	`73`	`return err`
`74`	`74`	`}`