CLI Reference

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.

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:

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

wails3 dev [flags]

Flags

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

Note

This is equivalent to running wails3 task dev and runs the dev task in the project’s main Taskfile. You can customise this by editing the Taskfile.yml file.

build

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

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:

wails3 build PLATFORM=linux CONFIG=production

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

# 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.

Note

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.

wails3 package [CLI variables...]

You can pass CLI variables to customize the packaging:

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

Note

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 that allows you to define and run custom build, test, and deployment tasks.

wails3 task [taskname] [CLI variables...] [flags]

CLI Variables

You can pass variables to tasks in the format KEY=VALUE:

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:

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

# 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.

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.

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.

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.

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.

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:

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):

info:
  cfBundleIconName: "appicon"

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

generate syso

Generates Windows .syso file.

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.

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.

wails3 generate runtime

generate constants

Generates JavaScript constants from Go code.

wails3 generate constants

generate webview2bootstrapper

Generates a Windows WebView2 bootstrap installer for distribution.

wails3 generate webview2bootstrapper [flags]

generate template

Scaffolds a new project template directory.

wails3 generate template [flags]

generate appimage

Generates a Linux AppImage.

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.

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.

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.

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.

wails3 tool cp

tool buildinfo

Shows build information about the application.

wails3 tool buildinfo

tool version

Bumps a semantic version based on the provided flags.

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:

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).

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.

wails3 tool lipo [flags]

Flags

Flag	Description	Default
-output	Output binary path

tool capabilities

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

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.

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.

wails3 tool has <tool>

Examples

# 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

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

tool has-cc

Deprecated

wails3 tool has-cc is deprecated. Update your Taskfile to use wails3 tool has gcc|clang instead.

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

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.

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:

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

update build-assets

Updates the build assets using the given config file.

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.

wails3 docs

releasenotes

Shows the release notes for the current or specified version.

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.

wails3 version

sponsor

Opens the Wails sponsorship page in your default browser.

wails3 sponsor