feat: add command aliasing via PATH lookup

Signed-off-by: olalekan odukoya <[email protected]>

Author: olamilekan000

cmd/limactl/main.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -40,7 +41,8 @@ func main() {
 			}
 		}
 	}
-	if err := newApp().Execute(); err != nil {
+	rootCmd := newApp()
+	if err := executeWithPluginSupport(rootCmd, os.Args[1:]); err != nil {
 		handleExitCoder(err)
 		logrus.Fatal(err)
 	}
@@ -61,18 +63,18 @@ func newApp() *cobra.Command {
 		Short:   "Lima: Linux virtual machines",
 		Version: strings.TrimPrefix(version.Version, "v"),
 		Example: fmt.Sprintf(`  Start the default instance:
-  $ limactl start
+	$ limactl start
 
-  Open a shell:
-  $ lima
+	Open a shell:
+	$ lima
 
-  Run a container:
-  $ lima nerdctl run -d --name nginx -p 8080:80 nginx:alpine
+	Run a container:
+	$ lima nerdctl run -d --name nginx -p 8080:80 nginx:alpine
 
-  Stop the default instance:
-  $ limactl stop
+	Stop the default instance:
+	$ limactl stop
 
-  See also template YAMLs: %s`, templatesDir),
+	See also template YAMLs: %s`, templatesDir),
 		SilenceUsage:      true,
 		SilenceErrors:     true,
 		DisableAutoGenTag: true,
@@ -215,6 +217,63 @@ func handleExitCoder(err error) {
 	}
 }
 
+// executeWithPluginSupport handles command execution with plugin support.
+func executeWithPluginSupport(rootCmd *cobra.Command, args []string) error {
+	if len(args) > 0 {
+		cmd, _, err := rootCmd.Find(args)
+		if err != nil || cmd == rootCmd {
+			if err := runExternalPlugin(args[0], args[1:]); err == nil {
+				return nil
+			}
+		}
+	}
+
+	rootCmd.SetArgs(args)
+	return rootCmd.Execute()
+}
+
+func runExternalPlugin(name string, args []string) error {
+	externalCmd := "limactl-" + name
+	execPath, err := exec.LookPath(externalCmd)
+	if err != nil {
+		return err
+	}
+
+	if err := updatePathEnv(); err != nil {
+		logrus.Warn("failed to update PATH environment: %v", err)
+		// PATH update failure shouldn't prevent plugin execution
+	}
+
+	logrus.Debugf("found external command: %s", execPath)
+
+	cmd := exec.Command(execPath, args...)
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.Env = os.Environ()
+
+	return cmd.Run()
+}
+
+func updatePathEnv() error {
+	exe, err := os.Executable()
+	if err != nil {
+		return fmt.Errorf("failed to get executable path: %w", err)
+	}
+
+	binDir := filepath.Dir(exe)
+	currentPath := os.Getenv("PATH")
+	newPath := binDir + string(filepath.ListSeparator) + currentPath
+
+	if err := os.Setenv("PATH", newPath); err != nil {
+		return fmt.Errorf("failed to set PATH environment: %w", err)
+	}
+
+	logrus.Debugf("updated PATH to prioritize %s", binDir)
+
+	return nil
+}
+
 // WrapArgsError annotates cobra args error with some context, so the error message is more user-friendly.
 func WrapArgsError(argFn cobra.PositionalArgs) cobra.PositionalArgs {
 	return func(cmd *cobra.Command, args []string) error {

website/content/en/docs/usage/_index.md

@@ -72,6 +72,61 @@ Then you can connect directly:
 ssh lima-default
 ```
 
+### Command Aliasing (Plugin System)
+
+Lima supports a plugin-like command aliasing system similar to `git`, `kubectl`, and `docker`. When you run a `limactl` command that doesn't exist, Lima will automatically look for an external program named `limactl-<command>` in your system's PATH.
+
+#### Creating Custom Aliases
+
+To create a custom alias, create an executable script with the name `limactl-<alias>` and place it somewhere in your PATH.
+
+**Example: Creating a `ps` alias for listing instances**
+
+1. Create a script called `limactl-ps`:
+   ```bash
+   #!/bin/sh
+   # Show instances in a compact format
+   limactl list --format table "$@"
+   ```
+
+2. Make it executable and place it in your PATH:
+   ```bash
+   chmod +x limactl-ps
+   sudo mv limactl-ps /usr/local/bin/
+   ```
+
+3. Now you can use it:
+   ```bash
+   limactl ps                    # Shows instances in table format
+   limactl ps --quiet            # Shows only instance names
+   ```
+
+**Example: Creating an `sh` alias**
+
+```bash
+#!/bin/sh
+# limactl-sh - Connect to an instance shell
+limactl shell "$@"
+```
+
+After creating this alias:
+```bash
+limactl sh default           # Equivalent to: limactl shell default
+limactl sh myinstance bash   # Equivalent to: limactl shell myinstance bash
+```
+
+#### How It Works
+
+1. When you run `limactl <unknown-command>`, Lima first tries to find a built-in command
+2. If no built-in command is found, Lima searches for `limactl-<unknown-command>` in your PATH
+3. If found, Lima executes the external program and passes all remaining arguments to it
+4. If not found, Lima shows the standard "unknown command" error
+
+This system allows you to:
+- Create personal shortcuts and aliases
+- Extend Lima's functionality without modifying the core application
+- Share custom commands with your team by distributing scripts
+
 ### Shell completion
 - To enable bash completion, add `source <(limactl completion bash)` to `~/.bash_profile`.
 - To enable zsh completion, see `limactl completion zsh --help`