CLI Reference

Complete reference for the Wails CLI commands

The Wails CLI provides a comprehensive set of commands to help you develop, build, and maintain your Wails applications.

Core Commands

Core commands are the primary commands used for project creation, development, and building.

All CLI commands are of the following format: wails3 <command>.

`init`

Initializes a new Wails project. During this initialization, the go mod tidy command is run to bring the project packages up to date. This can be bypassed by using the -skipgomodtidy flag with the init command.

bash

wails3 init [flags]

Flags

Flag	Description	Default
`-p`	Go package name	`main`
`-t`	Template name or URL	`vanilla`
`-n`	Project name
`-d`	Project directory	`.`
`-q`	Suppress output	`false`
`-l`	List templates	`false`
`-mod`	Go module path (computed from `-git` if omitted)
`-git`	Git repository URL
`-s`	Skip the warning when using a remote template	`false`
`-productname`	Product name	`My Product`
`-productdescription`	Product description	`My Product Description`
`-productversion`	Product version	`0.1.0`
`-productcompany`	Company name	`My Company`
`-productcopyright`	Copyright notice	`© now, My Company`
`-productcomments`	File comments	`This is a comment`
`-productidentifier`	Product identifier
`-skipgomodtidy`	Skip go mod tidy	`false`

The -git flag accepts various Git URL formats:

HTTPS: https://github.com/username/project
SSH: git@github.com:username/project or ssh://git@github.com/username/project
Git protocol: git://github.com/username/project
Filesystem: file:///path/to/project.git

When provided, this flag will:

Initialize a git repository in the project directory
Set the specified URL as the remote origin
Update the module name in go.mod to match the repository URL
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
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.

bash

wails3 dev [flags]

Flags

Flag	Description	Default
`-config`	Config file path	`./build/config.yml`
`-port`	Vite dev server port	`9245`
`-s`	Enable HTTPS	`false`

`build`

Builds a debug version of your application. It defaults to building for the current platform and architecture.

bash

wails3 build [flags] [CLI variables...]

Flags

Flag	Description	Default
`-tags`	Additional Go build tags (comma-separated)

You can pass CLI variables to customize the build:

bash

wails3 build PLATFORM=linux CONFIG=production

Use the -tags flag to pass custom Go build tags:

bash

# Build with legacy GTK3 + WebKit2GTK 4.1 on Linux (default is GTK4 + WebKitGTK 6.0)
wails3 build -tags gtk3

# Build in server mode (no GUI)
wails3 build -tags server

# Multiple tags
wails3 build -tags gtk3,customtag

Tags are forwarded as EXTRA_TAGS to the underlying Taskfile.

`package`

Creates platform-specific packages for distribution.

bash

wails3 package [CLI variables...]

You can pass CLI variables to customize the packaging:

bash

wails3 package VERSION=2.0.0 OUTPUT=myapp.pkg

Package Types

The following package types are available for each platform:

Platform	Package Type
Windows	`.exe`
macOS	`.app`,
Linux	`.AppImage`, `.deb`, `.rpm`, `.archlinux`

`task`

Runs tasks defined in your project’s Taskfile.yml. This is an embedded version of Taskfile 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
`-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

`mcp`

Starts the Wails project MCP server for agent-assisted project management. This is
separate from the MCP server compiled into a running application: wails3 mcp
manages project files and lifecycle commands, while the application MCP server
controls the running WebView.

bash

wails3 mcp [flags]

Transport is selected automatically:

When an MCP host launches Wails with piped stdin/stdout, the server uses stdio.
When run interactively in a terminal, the server uses Streamable HTTP on 127.0.0.1 and asks the operating system for a free port.

Use --stdio or --http to select a transport explicitly. Use --port 0 to choose a
free loopback port in HTTP mode.

MCP flags

Flag	Description	Default
`--root`	Allowed project root. Paths and symlinks outside it are rejected.	Current directory
`--token`	Session/bearer token for mutating and process-control tools. Falls back to `WAILS_MCP_TOKEN`.	Generated securely
`--stdio`	Force stdio transport.	Automatic
`--http`	Force Streamable HTTP transport.	Automatic
`--port`	HTTP port; `0` selects a free loopback port.	`0`

In HTTP mode, Wails prints the endpoint and bearer token to stderr. In stdio mode,
the token is included in the MCP initialization instructions. The server does not
expose arbitrary shell execution. Remote templates and Git remotes require explicit
approval through the tool’s allowExternal input.

`doctor`

Performs a system check and displays a status report.

bash

wails3 doctor

Generate Commands

Generate commands help create various project assets like bindings, icons, and build files. All generate commands use the base command: wails3 generate <command>.

`generate bindings`

Generates bindings and models for your Go code.

bash

wails3 generate bindings [flags] [patterns...]

Flags

Flag	Description	Default
`-f`	Additional Go build flags
`-d`	Output directory	`frontend/bindings`
`-models`	Models filename	`models`
`-index`	Index filename	`index`
`-ts`	Generate TypeScript	`false`
`-i`	Use TS interfaces	`false`
`-b`	Use bundled runtime	`false`
`-names`	Use names instead of IDs	`false`
`-noindex`	Skip index files	`false`
`-noevents`	Skip generating event-related bindings	`false`
`-dry`	Dry run	`false`
`-silent`	Silent mode	`false`
`-v`	Debug output	`false`
`-clean`	Clean output directory before generating	`true`

`generate build-assets`

Generates build assets for your application.

bash

wails3 generate build-assets [flags]

Flags

Flag	Description	Default
`-name`	Project name
`-dir`	Output directory	`build`
`-silent`	Suppress output	`false`
`-company`	Company name
`-productname`	Product name
`-description`	Product description
`-version`	Product version
`-identifier`	Product identifier	`com.wails.[name]`
`-copyright`	Copyright notice
`-comments`	File comments

`generate icons`

Generates application icons.

bash

wails3 generate icons [flags]

Flags

Flag	Description	Default
`-input`	Input PNG file	Required
`-windowsfilename`	Windows output filename
`-macfilename`	macOS output filename
`-sizes`	Icon sizes (comma-separated)	`256,128,64,48,32,16`
`-example`	Generate example icon	`false`
`-iconcomposerinput`	Input Icon Composer file (`.icon`)
`-macassetdir`	Output directory for Mac assets (Assets.car + icns)

Icon Composer (macOS)

On macOS 26+, you can use Icon Composer .icon files to generate Assets.car and icons.icns:

bash

wails3 generate icons -iconcomposerinput build/appicon.icon -macassetdir build

This compiles the .icon file using Apple’s actool command. Requires Xcode with actool version 26 or later.

When using Icon Composer, set cfBundleIconName in your build/config.yml to match the .icon filename (without extension):

yaml

info:
  cfBundleIconName: "appicon"

If not set and Assets.car exists, this defaults to "appicon".

`generate syso`

Generates Windows .syso file.

bash

wails3 generate syso [flags]

Flags

Flag	Description	Default
`-manifest`	Path to manifest file	Required
`-icon`	Path to icon file	Required
`-info`	Path to version info file
`-arch`	Target architecture	Current GOARCH
`-out`	Output filename	`rsrc_windows_[arch].syso`

`generate .desktop`

Generates a Linux .desktop file.

bash

wails3 generate .desktop [flags]

Flags

Flag	Description	Default
`-name`	Application name	Required
`-exec`	Executable path	Required
`-icon`	Icon path
`-categories`	Application categories	`Utility`
`-comment`	Application comment
`-terminal`	Run in terminal	`false`
`-keywords`	Search keywords
`-version`	Application version
`-genericname`	Generic name
`-startupnotify`	Show startup notification	`false`
`-mimetype`	Supported MIME types
`-output`	Output filename	`[name].desktop`

`generate runtime`

Generates the pre-built version of the runtime.

bash

wails3 generate runtime

`generate constants`

Generates JavaScript constants from Go code.

bash

wails3 generate constants

`generate webview2bootstrapper`

Generates a Windows WebView2 bootstrap installer for distribution.

bash

wails3 generate webview2bootstrapper [flags]

`generate template`

Scaffolds a new project template directory.

bash

wails3 generate template [flags]

`generate appimage`

Generates a Linux AppImage.

bash

wails3 generate appimage [flags]

Flags

Flag	Description	Default
`-binary`	Path to binary	Required
`-icon`	Path to icon file	Required
`-desktop`	Path to .desktop file	Required
`-builddir`	Build directory	Temp directory
`-output`	Output directory	`.`

Service Commands

Service commands help manage Wails services. All service commands use the base command: wails3 service <command>.

`service init`

Initializes a new service.

bash

wails3 service init [flags]

Flags

Flag	Description	Default
`-n`	Service name	`example_service`
`-d`	Service description	`Example service`
`-p`	Package name
`-o`	Output directory	`.`
`-q`	Suppress output	`false`
`-a`	Author name
`-v`	Version
`-w`	Website URL
`-r`	Repository URL
`-l`	License

Tool Commands

Tool commands provide utilities for development and debugging. All tool commands use the base command: wails3 tool <command>.

`tool checkport`

Checks if a port is open. Useful for testing if vite is running.

bash

wails3 tool checkport [flags]

Flags

Flag	Description	Default
`-port`	Port to check	`9245`
`-host`	Host to check	`localhost`

`tool watcher`

Watches files and runs a command when they change.

bash

wails3 tool watcher [flags]

Flags

Flag	Description	Default
`-config`	Config file path	`./build/config.yml`
`-ignore`	Patterns to ignore
`-include`	Patterns to include

`tool cp`

Copies files.

bash

wails3 tool cp

`tool buildinfo`

Shows build information about the application.

bash

wails3 tool buildinfo

`tool version`

Bumps a semantic version based on the provided flags.

bash

wails3 tool version [flags]

Flags

Flag	Description	Default
`-v`	Current version to bump
`-major`	Bump major version	`false`
`-minor`	Bump minor version	`false`
`-patch`	Bump patch version	`false`
`-prerelease`	Bump prerelease version (e.g., alpha.5 to alpha.6)	`false`

The command follows the precedence order: major > minor > patch > prerelease. It preserves the “v” prefix if present in the input version, as well as any prerelease and metadata components.

Example usage:

bash

wails3 tool version -v 1.2.3 -major      # Output: 2.0.0
wails3 tool version -v v1.2.3 -minor     # Output: v1.3.0
wails3 tool version -v 1.2.3-alpha -patch # Output: 1.2.4-alpha
wails3 tool version -v v3.0.0-alpha.5 -prerelease # Output: v3.0.0-alpha.6

`tool package`

Generates Linux packages (deb, rpm, archlinux).

bash

wails3 tool package [flags]

Flags

Flag	Description	Default
`-format`	Package format (deb, rpm, archlinux)	`deb`
`-name`	Executable name	`myapp`
`-config`	Config file path
`-out`	Output directory	`.`

`tool lipo`

Creates a macOS universal binary by combining architecture-specific binaries.

bash

wails3 tool lipo [flags]

Flags

Flag	Description	Default
`-output`	Output binary path

`tool capabilities`

Checks system build capabilities (GTK4/GTK3 availability on Linux).

bash

wails3 tool capabilities

`tool docker-mounts`

Generates Docker volume mount flags for cross-compilation. Outputs -v flags for the Go module cache and any local replace directives in go.mod, for use in Taskfile docker run commands.

bash

wails3 tool docker-mounts

`tool has`

Checks whether a tool or capability is available, printing true or false to stdout. Designed for use in Taskfile sh: variables as a cross-platform alternative to command -v.

Use | to check for any one of several alternatives.

bash

wails3 tool has <tool>

Examples

bash

# Check for a C compiler (gcc or clang)
wails3 tool has gcc|clang

# Check for a specific tool
wails3 tool has git
wails3 tool has node

Usage in a Taskfile

yaml

vars:
  HAS_CC:
    sh: 'wails3 tool has gcc|clang'

`tool has-cc`

A backward-compatible alias for wails3 tool has gcc|clang. Checks whether gcc or clang is available in PATH and prints true or false.

bash

wails3 tool has-cc

Update Commands

Update commands help manage and update project assets. All update commands use the base command: wails3 update <command>.

`update cli`

Updates the Wails CLI to a new version.

bash

wails3 update cli [flags]

Flags

Flag	Description	Default
`-pre`	Update to latest pre-release	`false`
`-version`	Update to specific version
`-nocolour`	Disable colored output	`false`

The update cli command allows you to update your Wails CLI installation. By default, it updates to the latest stable release.
You can use the -pre flag to update to the latest pre-release version, or specify a particular version using the -version flag.

After updating, remember to update your project’s go.mod file to use the same version:

bash

require github.com/wailsapp/wails/v3 v3.x.x

`update build-assets`

Updates the build assets using the given config file.

bash

wails3 update build-assets [flags]

Flags

Flag	Description	Default
`-config`	Config file path
`-dir`	Output directory	`build`
`-silent`	Suppress output	`false`
`-company`	Company name
`-productname`	Product name
`-description`	Product description
`-version`	Product version
`-identifier`	Product identifier
`-copyright`	Copyright notice
`-comments`	File comments

Utility Commands

Utility commands provide helpful shortcuts for common tasks. Use these commands directly with the base command: wails3 <command>.

`docs`

Opens the Wails documentation in your default browser.

bash

wails3 docs

`releasenotes`

Shows the release notes for the current or specified version.

bash

wails3 releasenotes [flags]

Flags

Flag	Description	Default
`-v`	Version to show release notes for
`-n`	Disable colour output	`false`

`version`

Prints the current version of Wails.

bash

wails3 version

`sponsor`

Opens the Wails sponsorship page in your default browser.

bash

wails3 sponsor