---
title: CLI Reference
description: Complete reference for the Wails CLI commands
sidebar:
  order: 1
---

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`                  | Package name         | `main`                   |
| `-t`                  | Template name or URL | `vanilla`                |
| `-n`                  | Project name         |                          |
| `-d`                  | Project directory    | `.`                      |
| `-q`                  | Suppress output      | `false`                  |
| `-l`                  | List templates       | `false`                  |
| `-git`                | Git repository URL   |                          |
| `-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.

```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`              |


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

```bash
wails3 build [CLI variables...]
```

You can pass CLI variables to customize the build:
```bash
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. 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 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](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.

```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`             |
| `-dry`      | Dry run                   | `false`             |
| `-silent`   | Silent mode               | `false`             |
| `-v`        | Debug output              | `false`             |
| `-clean`    | Clean output directory    | `false`             |

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

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

Base command: `wails3 service`

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

Base command: `wails3 tool`

## 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                      | Required |
| `-config` | Config file path                     | Required |
| `-out`    | Output directory                     | `.`      |

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

Base command: `wails3 update`

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

Base command: `wails3`

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