Skip to main content
Version: Next Version ๐Ÿšง

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
-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.
-cleanCleans the build/bin directory
-compiler "compiler"Use a different go compiler to build, eg go1.15beta1go
-ldflags "flags"Additional ldflags to pass to the compiler
-nopackageDo not package application
-o filenameOutput filename
-sSkip building the frontendfalse
-fForce build applicationfalse
-tags "extra tags"Build tags to pass to Go compiler. Must be quoted. Space or comma (but not both) separated
-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
-uUpdates your project's go.mod to use the same version of Wails as the CLI
-debugRetains debug information in the application. Allows the use of the devtools in the application windowfalse
-trimpathRemove all file system paths from the resulting executable.false
-raceBuild with Go's race detectorfalse
-windowsconsoleKeep the console window for Windows buildsfalse

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

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.17
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
FlagDescriptionDefault
-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
-eExtensions to trigger rebuilds (comma separated)go
-reloaddirsAdditional directories to trigger reloads (comma separated)Value in wails.json
-ldflags "flags"Additional ldflags to pass to the compiler
-tags "extra tags"Build tags to pass to compiler (quoted and space separated)
-loglevel "loglevel"Loglevel to use - Trace, Debug, Info, Warning, ErrorDebug
-noreloadDisable automatic reload when assets change
-nogenDisable generate module
-vVerbosity level (0 - silent, 1 - standard, 2 - verbose)1
-wailsjsdirThe directory to generate the generated Wails JS modulesValue in wails.json
-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"
-frontenddevserverurl "url"Use 3rd party dev server url to serve assets, EG Vite""
-appargs "args"Arguments passed to the application in shell style
-saveSaves the given assetdir, reloaddirs, wailsjsdir, debounce, devserver and frontenddevserverurl flags in wails.json to become the defaults for subsequent invocations.
-raceBuild with Go's race detectorfalse
-sSkip building the frontendfalse

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.

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.