Skip to main content
Version: v2.8.0

CLI

The Wails CLI has a number of commands that are used for managing your projects. All commands are run in the following way:

wails <command> <flags>

init

wails init is used for generating projects.

FlagDescriptionDefault
-n "project name"Name of the project. Mandatory.
-d "project dir"Project directory to createName of the project
-gInitialise git repository
-lList available project templates
-qSuppress output to console
-t "template name"The project template to use. This can be the name of a default template or a URL to a remote template hosted on github.vanilla
-ideGenerate IDE project files
-fForce build applicationfalse

Example: wails init -n test -d mytestproject -g -ide vscode -q

This will generate a a project called "test" in the "mytestproject" directory, initialise git, generate vscode project files and do so silently.

More information on using IDEs with Wails can be found here.

Remote Templates

Remote templates (hosted on GitHub) are supported and can be installed by using the template's project URL.

Example: wails init -n test -t https://github.com/leaanthony/testtemplate[@v1.0.0]

A list of community maintained templates can be found here

Attention

The Wails project does not maintain, is not responsible nor liable for 3rd party templates!

If you are unsure about a template, inspect package.json and wails.json for what scripts are run and what packages are installed.

build

wails build is used for compiling your project to a production-ready binary.

FlagDescriptionDefault
-cleanCleans the build/bin directory
-compiler "compiler"Use a different go compiler to build, eg go1.15beta1go
-debugRetains debug information in the application and shows the debug console. Allows the use of the devtools in the application window
-devtoolsAllows the use of the devtools in the application window in production (when -debug is not used). Ctrl/Cmd+Shift+F12 may be used to open the devtools window. NOTE: This option will make your application FAIL Mac appstore guidelines. Use for debugging only.
-dryrunPrints the build command without executing it
-fForce build application
-garbleargsArguments to pass to garble-literals -tiny -seed=random
-ldflags "flags"Additional ldflags to pass to the compiler
-mSkip mod tidy before compile
-nopackageDo not package application
-nocolourDisable colour in output
-nosyncgomodDo not sync go.mod with the Wails version
-nsisGenerate NSIS installer for Windows
-o filenameOutput filename
-obfuscatedObfuscate the application using garble
-platformBuild for the given (comma delimited) platforms eg. windows/arm64. Note, if you do not give the architecture, runtime.GOARCH is used.platform = GOOS environment variable if given else runtime.GOOS.
arch = GOARCH envrionment variable if given else runtime.GOARCH.
-raceBuild with Go's race detector
-sSkip building the frontend
-skipbindingsSkip bindings generation
-tags "extra tags"Build tags to pass to Go compiler. Must be quoted. Space or comma (but not both) separated
-trimpathRemove all file system paths from the resulting executable.
-uUpdates your project's go.mod to use the same version of Wails as the CLI
-upxCompress final binary using "upx"
-upxflagsFlags to pass to upx
-v intVerbosity level (0 - silent, 1 - default, 2 - verbose)1
-webview2WebView2 installer strategy: download,embed,browser,errordownload
-windowsconsoleKeep the console window for Windows builds

For a detailed description of the webview2 flag, please refer to the Windows Guide.

If you prefer to build using standard Go tooling, please consult the Manual Builds guide.

Example:

wails build -clean -o myproject.exe

info

On Mac, the application will be bundled with Info.plist, not Info.dev.plist.

UPX on Apple Silicon

There are issues with using UPX with Apple Silicon.

UPX on Windows

Some Antivirus vendors false positively mark upx compressed binaries as virus, see issue.

Platforms

Supported platforms are:

PlatformDescription
darwinMacOS + architecture of build machine
darwin/amd64MacOS 10.13+ AMD64
darwin/arm64MacOS 11.0+ ARM64
darwin/universalMacOS AMD64+ARM64 universal application
windowsWindows 10/11 + architecture of build machine
windows/amd64Windows 10/11 AMD64
windows/arm64Windows 10/11 ARM64
linuxLinux + architecture of build machine
linux/amd64Linux AMD64
linux/arm64Linux ARM64

doctor

wails doctor will run diagnostics to ensure that your system is ready for development.

Example:

Wails CLI v2.0.0-beta

Scanning system - Please wait (this may take a long time)...Done.

System
------
OS: Windows 10 Pro
Version: 2009 (Build: 19043)
ID: 21H1
Go Version: go1.18
Platform: windows
Architecture: amd64

Dependency Package Name Status Version
---------- ------------ ------ -------
WebView2 N/A Installed 93.0.961.52
npm N/A Installed 6.14.15
*upx N/A Installed upx 3.96

* - Optional Dependency

Diagnosis
---------
Your system is ready for Wails development!

dev

wails dev is used to run your application in a "live development" mode. This means:

  • The application's go.mod will be updated to use the same version of Wails as the CLI
  • The application is compiled and run automatically
  • A watcher is started and will trigger a rebuild of your dev app if it detects changes to your go files
  • A webserver is started on http://localhost:34115 which serves your application (not just frontend) over http. This allows you to use your favourite browser development extensions
  • All application assets are loaded from disk. If they are changed, the application will automatically reload (not rebuild). All connected browsers will also reload
  • A JS module is generated that provides the following:
  • JavaScript wrappers of your Go methods with autogenerated JSDoc, providing code hinting
  • TypeScript versions of your Go structs, that can be constructed and passed to your go methods
  • A second JS module is generated that provides a wrapper + TS declaration for the runtime
  • On macOS, it will bundle the application into a .app file and run it. It will use a build/darwin/Info.dev.plist for development.
FlagDescriptionDefault
-appargs "args"Arguments passed to the application in shell style
-assetdir "./path/to/assets"Serve assets from the given directory instead of using the provided asset FSValue in wails.json
-browserOpens a browser to http://localhost:34115 on startup
-compiler "compiler"Use a different go compiler to build, eg go1.15beta1go
-debounceThe time to wait for reload after an asset change is detected100 (milliseconds)
-devserver "host:port"The address to bind the wails dev server to"localhost:34115"
-extensionsExtensions to trigger rebuilds (comma separated)go
-forcebuildForce build of application
-frontenddevserverurl "url"Use 3rd party dev server url to serve assets, EG Vite""
-ldflags "flags"Additional ldflags to pass to the compiler
-loglevel "loglevel"Loglevel to use - Trace, Debug, Info, Warning, ErrorDebug
-nocolourTurn off colour cli outputfalse
-noreloadDisable automatic reload when assets change
-nosyncgomodDo not sync go.mod with the Wails versionfalse
-raceBuild with Go's race detectorfalse
-reloaddirsAdditional directories to trigger reloads (comma separated)Value in wails.json
-sSkip building the frontendfalse
-saveSaves the given assetdir, reloaddirs, wailsjsdir, debounce, devserver and frontenddevserverurl flags in wails.json to become the defaults for subsequent invocations.
-skipbindingsSkip bindings generation
-tags "extra tags"Build tags to pass to compiler (quoted and space separated)
-vVerbosity level (0 - silent, 1 - standard, 2 - verbose)1
-wailsjsdirThe directory to generate the generated Wails JS modulesValue in wails.json

Example:

wails dev -assetdir ./frontend/dist -wailsjsdir ./frontend/src -browser

This command will do the following:

  • Build the application and run it (more details here
  • Generate the Wails JS modules in ./frontend/src
  • Watch for updates to files in ./frontend/dist and reload on any change
  • Open a browser and connect to the application

There is more information on using this feature with existing framework scripts here.

generate

template

Wails uses templates for project generation. The wails generate template command helps scaffold a template so that it may be used for generating projects.

FlagDescription
-nameThe template name (Mandatory)
-frontend "path"Path to frontend project to use in template

For more details on creating templates, consult the Templates guide.

module

The wails generate module command allows you to manually generate the wailsjs directory for your application.

FlagDescriptionDefault
-compiler "compiler"Use a different go compiler to build, eg go1.15beta1go
-tags "extra tags"Build tags to pass to compiler (quoted and space separated)

update

wails update will update the version of the Wails CLI.

FlagDescription
-preUpdate to latest pre-release version
-version "version"Install a specific version of the CLI

version

wails version will simply output the current CLI version.