Update CLI to pass through variables

docs/src/content/docs/guides/cli.mdx

@@ -1,6 +1,7 @@
 ---
 title: CLI Reference
 description: Complete reference for the Wails CLI commands
+sidebar:
 sidebar:
   order: 1
 ---
@@ -9,7 +10,7 @@ The Wails CLI provides a comprehensive set of commands to help you develop, buil
 
 ## Core Commands
 
-Core commands are the primary commands used for project creation, development, and building. 
+Core commands are the primary commands used for project creation, development, and building.
 
 All CLI commands are of the following format: `wails3 <command>`.
 
@@ -52,7 +53,7 @@ When provided, this flag will:
 4. Add all files
 
 ### `dev`
-Runs the application in development mode. This will give you a live view of your frontend code, and you can make changes and see them reflected 
+Runs the application in development mode. This will give you a live view of your frontend code, and you can make changes and see them reflected
 in the running application without having to rebuild the entire application. Changes to your Go code will also be detected and the application
 will automatically rebuild and relaunch.
 
@@ -76,22 +77,30 @@ wails3 dev [flags]
 ### `build`
 Builds a debug version of your application. It defaults to building for the current platform and architecture.
 
+```bash
+wails3 build [CLI variables...]
+```
 
+You can pass CLI variables to customize the build:
 ```bash
-wails3 build
+wails3 build PLATFORM=linux CONFIG=production
 ```
 
     :::note
-    This is equivalent to running `wails3 task build` which runs the `build` task in the project's main Taskfile. You can customise the build process by editing the `Taskfile.yml` file.
+    This is equivalent to running `wails3 task build` which runs the `build` task in the project's main Taskfile. Any CLI variables passed to `build` are forwarded to the underlying task. You can customise the build process by editing the `Taskfile.yml` file.
     :::
 
 ### `package`
 
 Creates platform-specific packages for distribution.
 
+```bash
+wails3 package [CLI variables...]
+```
 
+You can pass CLI variables to customize the packaging:
 ```bash
-wails3 package
+wails3 package VERSION=2.0.0 OUTPUT=myapp.pkg
 ```
 
 #### Package Types
@@ -104,13 +113,80 @@ The following package types are available for each platform:
 | macOS    | `.app`,                                   |
 | Linux    | `.AppImage`, `.deb`, `.rpm`, `.archlinux` |
 
-
-
     :::note
-     This is equivalent to `wails3 task package` which runs the `package` task in the project's main Taskfile. You can customise the packaging process by editing the `Taskfile.yml` file.
+     This is equivalent to `wails3 task package` which runs the `package` task in the project's main Taskfile. Any CLI variables passed to `package` are forwarded to the underlying task. You can customise the packaging process by editing the `Taskfile.yml` file.
     :::
 
 
+### `task`
+Runs tasks defined in your project's Taskfile.yml. This is an embedded version of [Taskfile](https://taskfile.dev) that allows you to define and run custom build, test, and deployment tasks.
+
+```bash
+wails3 task [taskname] [CLI variables...] [flags]
+```
+
+#### CLI Variables
+You can pass variables to tasks in the format `KEY=VALUE`:
+```bash
+wails3 task build PLATFORM=linux CONFIG=production
+wails3 task deploy ENV=staging VERSION=1.2.3
+```
+
+These variables can be accessed in your Taskfile.yml using Go template syntax:
+```yaml
+tasks:
+  build:
+    cmds:
+      - echo "Building for {{.PLATFORM | default "darwin"}}"
+      - echo "Config: {{.CONFIG | default "debug"}}"
+```
+
+#### Flags
+| Flag         | Description                               | Default  |
+|--------------|-------------------------------------------|----------|
+| `-h`         | Shows Task usage                          | `false`  |
+| `-i`         | Creates a new Taskfile.yml                | `false`  |
+| `-list`      | Lists tasks with descriptions             | `false`  |
+| `-list-all`  | Lists all tasks (with or without descriptions) | `false`  |
+| `-json`      | Formats task list as JSON                 | `false`  |
+| `-status`    | Exits with non-zero if task is not up-to-date | `false`  |
+| `-f`         | Forces execution even when task is up-to-date | `false`  |
+| `-w`         | Enables watch mode for the given task     | `false`  |
+| `-v`         | Enables verbose mode                      | `false`  |
+| `-version`   | Prints Task version                       | `false`  |
+| `-s`         | Disables echoing                          | `false`  |
+| `-p`         | Executes tasks in parallel                | `false`  |
+| `-dry`       | Compiles and prints tasks without executing | `false`  |
+| `-summary`   | Shows summary about a task                | `false`  |
+| `-x`         | Pass-through the exit code of the task    | `false`  |
+| `-dir`       | Sets directory of execution               |          |
+| `-taskfile`  | Choose which Taskfile to run              |          |
+| `-output`    | Sets output style: [interleaved|group|prefixed] |          |
+| `-c`         | Colored output (enabled by default)       | `true`   |
+| `-C`         | Limit number of tasks to run concurrently |          |
+| `-interval`  | Interval to watch for changes (in seconds) |          |
+
+#### Examples
+```bash
+# Run the default task
+wails3 task
+
+# Run a specific task
+wails3 task test
+
+# Run a task with variables
+wails3 task build PLATFORM=windows ARCH=amd64
+
+# List all available tasks
+wails3 task --list
+
+# Run multiple tasks in parallel
+wails3 task -p task1 task2 task3
+
+# Watch for changes and re-run task
+wails3 task -w dev
+```
+
 ### `doctor`
 Performs a system check and displays a status report.
 

docs/src/content/docs/learn/build.mdx

@@ -138,6 +138,29 @@ commands, Wails internally translates them to the appropriate task execution:
 - `wails3 build` → `wails3 task build`
 - `wails3 package` → `wails3 task package`
 
+### Passing Parameters to Tasks
+
+You can pass CLI variables to tasks using the `KEY=VALUE` format. These variables are forwarded through the alias commands:
+
+```bash
+# These are equivalent:
+wails3 build PLATFORM=linux CONFIG=production
+wails3 task build PLATFORM=linux CONFIG=production
+
+# Package with custom version:
+wails3 package VERSION=2.0.0 OUTPUT=myapp.pkg
+```
+
+In your `Taskfile.yml`, you can access these variables using Go template syntax:
+
+```yaml
+tasks:
+  build:
+    cmds:
+      - echo "Building for {{.PLATFORM | default "darwin"}}"
+      - go build -tags {{.CONFIG | default "debug"}} -o myapp
+```
+
 ## Common Build Process
 
 Across all platforms, the build process typically includes the following steps:

v3/UNRELEASED_CHANGELOG.md

@@ -18,6 +18,7 @@ After processing, the content will be moved to the main changelog and this file
 ## Added
 <!-- New features, capabilities, or enhancements -->
 - Add Content Protection on Windows/Mac by [@leaanthony](https://github.com/leaanthony) based on the original work of [@Taiterbase](https://github.com/Taiterbase) in this [PR](https://github.com/wailsapp/wails/pull/4241)
+- Add support for passing CLI variables to Task commands through `wails3 build` and `wails3 package` aliases (#4422) by @leaanthony in [PR](https://github.com/wailsapp/wails/pull/4488)
 
 ## Changed
 <!-- Changes in existing functionality -->

v3/cmd/wails3/main.go

@@ -33,9 +33,22 @@ func main() {
 	app := clir.NewCli("wails", "The Wails3 CLI", "v3")
 	app.NewSubCommand("docs", "Open the docs").Action(openDocs)
 	app.NewSubCommandFunction("init", "Initialise a new project", commands.Init)
-	app.NewSubCommandFunction("build", "Build the project", commands.Build)
+
+	build := app.NewSubCommand("build", "Build the project")
+	var buildFlags flags.Build
+	build.AddFlags(&buildFlags)
+	build.Action(func() error {
+		return commands.Build(&buildFlags, build.OtherArgs())
+	})
+
 	app.NewSubCommandFunction("dev", "Run in Dev mode", commands.Dev)
-	app.NewSubCommandFunction("package", "Package application", commands.Package)
+
+	pkg := app.NewSubCommand("package", "Package application")
+	var pkgFlags flags.Package
+	pkg.AddFlags(&pkgFlags)
+	pkg.Action(func() error {
+		return commands.Package(&pkgFlags, pkg.OtherArgs())
+	})
 	app.NewSubCommandFunction("doctor", "System status report", commands.Doctor)
 	app.NewSubCommandFunction("releasenotes", "Show release notes", commands.ReleaseNotes)
 

v3/go.mod

@@ -32,6 +32,7 @@ require (
 	github.com/pkg/errors v0.9.1
 	github.com/pterm/pterm v0.12.80
 	github.com/samber/lo v1.49.1
+	github.com/stretchr/testify v1.10.0
 	github.com/tc-hib/winres v0.3.1
 	github.com/wailsapp/go-webview2 v1.0.21
 	github.com/wailsapp/mimetype v1.4.1
@@ -50,6 +51,7 @@ require (
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
 )
 
 require (

v3/internal/commands/task.go

@@ -123,29 +123,62 @@ func RunTask(options *RunTaskOptions, otherArgs []string) error {
 		return nil
 	}
 
-	var index int
-	var arg string
-	for index, arg = range os.Args[2:] {
-		if !strings.HasPrefix(arg, "-") {
-			break
+	// Parse task name and CLI variables from otherArgs or os.Args
+	var tasksAndVars []string
+
+	// Check if we have a task name specified in options
+	if options.Name != "" {
+		// If task name is provided via options, use it and treat otherArgs as CLI variables
+		tasksAndVars = append([]string{options.Name}, otherArgs...)
+	} else if len(otherArgs) > 0 {
+		// Use otherArgs directly if provided
+		tasksAndVars = otherArgs
+	} else {
+		// Fall back to parsing os.Args for backward compatibility
+		var index int
+		var arg string
+		for index, arg = range os.Args[2:] {
+			if !strings.HasPrefix(arg, "-") {
+				break
+			}
 		}
-	}
 
-	var tasksAndVars []string
-	for _, taskAndVar := range os.Args[index+2:] {
-		if taskAndVar == "--" {
-			break
+		for _, taskAndVar := range os.Args[index+2:] {
+			if taskAndVar == "--" {
+				break
+			}
+			tasksAndVars = append(tasksAndVars, taskAndVar)
 		}
-		tasksAndVars = append(tasksAndVars, taskAndVar)
 	}
 
-	if len(tasksAndVars) > 0 && len(otherArgs) > 0 {
-		if tasksAndVars[0] == otherArgs[0] {
-			otherArgs = otherArgs[1:]
+	// Default task
+	if len(tasksAndVars) == 0 {
+		tasksAndVars = []string{"default"}
+	}
+
+	// Parse task name and CLI variables
+	taskName := tasksAndVars[0]
+	cliVars := tasksAndVars[1:]
+
+	// Create call with CLI variables
+	call := &ast.Call{
+		Task: taskName,
+		Vars: &ast.Vars{},
+	}
+
+	// Parse CLI variables (format: KEY=VALUE)
+	for _, v := range cliVars {
+		if strings.Contains(v, "=") {
+			parts := strings.SplitN(v, "=", 2)
+			if len(parts) == 2 {
+				call.Vars.Set(parts[0], ast.Var{
+					Value: parts[1],
+				})
+			}
 		}
 	}
 
-	if err := e.RunTask(context.Background(), &ast.Call{Task: tasksAndVars[0]}); err != nil {
+	if err := e.RunTask(context.Background(), call); err != nil {
 		fatal(err.Error())
 	}
 	return nil