Gondwana CLI Cheatsheet

Quick reference for all gondwana commands and their options.

Installation

Install the CLI as a .NET global tool from NuGet:

dotnet tool install --global Gondwana.Cli

Update to the latest version:

dotnet tool update --global Gondwana.Cli

Uninstall:

dotnet tool uninstall --global Gondwana.Cli

After installation the gondwana command is available in any terminal.

Top-level commands

Command	Description
`gondwana help`	Show a summary of all available commands.
`gondwana doctor`	Validate your local Gondwana development environment. Pass `--fix` to auto-fix issues.
`gondwana info`	Show information about the Gondwana project in the current directory.
`gondwana assets <subcommand>`	Pack, inspect, extract, and generate keys for Gondwana asset files.
`gondwana pack <source> <output>`	Pack a directory of files into an asset bundle (shorthand for `gondwana assets pack`).
`gondwana new <winforms\|avalonia\|blazor> <name>`	Scaffold a new WinForms, Avalonia, or Blazor WebAssembly Gondwana project.
`gondwana run [<subcommand>]`	Run the desktop project by default, or run a supported subcommand such as `blazor`.
`gondwana publish [<subcommand>]`	Publish the desktop project by default, or publish a supported target such as `blazor` or `itch`.
`gondwana deploy [<subcommand>]`	Deploy the Blazor/WebAssembly project by default, or deploy a supported target such as `itch`.
`gondwana templates <subcommand>`	Manage Gondwana `dotnet new` templates.

📜 `gondwana help`

Prints a formatted table of all available commands with short descriptions, then reminds you to run gondwana <command> --help for detailed usage.

No arguments or options.

📜 `gondwana doctor`

Checks the local environment for all Gondwana prerequisites (.NET SDK, templates, release/deploy tooling, native libraries).

Option	Description
`--fix`	Automatically fix issues that can be resolved without manual steps. After applying fixes, all checks are re-run and the updated results are displayed.

Currently auto-fixable:

Gondwana CLI not installed → runs dotnet tool install -g Gondwana.Cli
Gondwana Templates missing → runs dotnet new install Gondwana.Templates; if already installed, --fix runs dotnet new update instead so newer local template packages are retained rather than downgraded
wasm-tools not installed → runs dotnet workload install wasm-tools
git-cliff on Windows → runs winget install/upgrade --id orhun.git-cliff
butler not installed → downloads the latest binary from the itch.io broth CDN and installs it to %LOCALAPPDATA%\itch\butler (Windows) or ~/.itch/butler (Linux/macOS). Run butler login after installation to authenticate with itch.io.

Examples

gondwana doctor
gondwana doctor --fix

📜 `gondwana info`

Reads the .csproj in the current directory and prints project metadata (name, target framework, Gondwana version, adapters, and discovered asset bundles). When multiple .csproj files are present, the first one alphabetically is used.

No arguments or options.

📜 `gondwana assets`

Subcommand	Description
`pack`	Pack a directory of files into an asset bundle.
`list`	List all assets in a bundle.
`extract`	Extract all assets from a bundle to a directory.
`generate-keys`	Generate a C# constants class for all asset keys in a bundle.

`gondwana assets pack <source> <output>`

Argument / Option	Short	Default	Description
`<source>`			Required. Source directory containing files to pack.
`<output>`			Required. Output bundle file path (e.g. `game.assets` or `game.gaf`).
`--type <name>`	`-t`	`Misc`	Default asset type for files whose type cannot be inferred from the extension.
`--recurse`	`-r`	`true`	Recurse into subdirectories.
`--append`	`-a`	`false`	Append to an existing bundle instead of overwriting it. By default the output file is deleted first so no stale entries survive a re-run.
`--type-map <file>`	`-m`	(built-in defaults)	Path to a JSON file that maps asset types to file extensions. Optional. Resolution order: this flag → `gondwana-asset-types.json` in CWD → `gondwana-asset-types.json` next to the executable → built-in defaults.
`--password <value>`	`-p`	(none)	Password-protect the bundle. Required when `--encrypt` is used.
`--encrypt`	`-e`	`false`	Encrypt the bundle using AES-256. Requires `--password`.

Examples

gondwana assets pack ./Assets ./game.assets
gondwana assets pack ./Assets ./game.assets --append
gondwana assets pack ./Assets ./game.assets -m ./my-types.json
gondwana assets pack ./Assets ./game.assets --password secret
gondwana assets pack ./Assets ./game.assets --password secret --encrypt

`gondwana assets list <file>`

Argument / Option	Short	Description
`<file>`		Required. Path to the asset bundle to inspect.
`--type <name>`	`-t`	Filter output to assets of the specified type (e.g. `Image`, `Audio`, `Video`, `Font`, `Cursor`, `Svg`, `Misc`).
`--password <value>`	`-p`	Password required to open a password-protected or encrypted bundle.

Example

gondwana assets list ./game.assets
gondwana assets list ./game.assets -t Image
gondwana assets list ./game.assets --password secret

`gondwana assets extract <file> <output>`

Argument / Option	Short	Default	Description
`<file>`			Required. Path to the asset bundle to extract.
`<output>`			Required. Directory to extract assets into. Created automatically if it does not exist.
`--type <name>`	`-t`	(all)	Extract only assets of the specified type (e.g. `Image`, `Audio`).
`--overwrite`		`false`	Overwrite existing files in the output directory.
`--password <value>`	`-p`	(none)	Password required to open a password-protected or encrypted bundle.

Example

gondwana assets extract ./game.assets ./Extracted
gondwana assets extract ./game.assets ./Extracted --overwrite -t Audio
gondwana assets extract ./game.assets ./Extracted --password secret

`gondwana assets generate-keys <file>`

Generates a C# public static class containing one public const string per asset key, suitable for use at compile time.

Argument / Option	Short	Default	Description
`<file>`			Required. Path to the asset bundle to read keys from.
`--output <file>`	`-o`	(stdout)	Output `.cs` file path. Prints to stdout if omitted. The destination directory is created automatically if it does not exist.
`--namespace <ns>`	`-n`	(none)	C# namespace for the generated class.
`--class <name>`	`-c`	`AssetKeys`	C# class name.
`--password <value>`	`-p`	(none)	Password required to open a password-protected or encrypted bundle.
`--include-loader`	`-l`	`false`	Add a `Load(string? password = null)` static method that instantiates an `AssetsFile` for the bundle.

Examples

gondwana assets generate-keys ./game.assets
gondwana assets generate-keys ./game.assets -o ./Generated/AssetKeys.cs -n MyGame -c AssetKeys
gondwana assets generate-keys ./game.assets --password secret
gondwana assets generate-keys ./game.assets --include-loader -o ./Generated/AssetKeys.cs -n MyGame

📜 `gondwana pack`

Top-level shorthand for gondwana assets pack. Accepts exactly the same arguments and options.

Examples

gondwana pack ./Assets ./game.assets
gondwana pack ./Assets ./game.assets --append
gondwana pack ./Assets ./game.assets -m ./my-types.json
gondwana pack ./Assets ./game.assets --password secret
gondwana pack ./Assets ./game.assets --password secret --encrypt

📜 `gondwana new`

Subcommand	Description
`winforms`	Create a new WinForms Gondwana project.
`avalonia`	Create a new Avalonia Gondwana project (Windows, macOS, Linux).
`blazor`	Create a new Blazor WebAssembly Gondwana project for browser.

`gondwana new winforms <name>`

If a .sln already exists in the output directory, adds the generated project to it; otherwise creates <name>.sln and adds the project.

Argument / Option	Short	Default	Description
`<name>`			Required. Name of the new project.
`--output <dir>`	`-o`		Directory to place the generated output in. Defaults to a new folder named `<name>` in the current directory.
`--backbuffer <type>`	`-b`	`bitmap`	Backbuffer type: `bitmap` (CPU-based, default) or `gpu` (OpenGL-accelerated).

Example

gondwana new winforms MyGame
gondwana new winforms MyGame -o ./projects/MyGame
gondwana new winforms MyGame --backbuffer gpu

`gondwana new avalonia <name>`

If a .sln already exists in the output directory, adds the generated project to it; otherwise creates <name>.sln and adds the project.

Argument / Option	Short	Default	Description
`<name>`			Required. Name of the new project.
`--output <dir>`	`-o`		Directory to place the generated output in. Defaults to a new folder named `<name>` in the current directory.
`--backbuffer <type>`	`-b`	`bitmap`	Backbuffer type: `bitmap` (CPU-based, default) or `gpu` (OpenGL-accelerated).

Example

gondwana new avalonia MyGame
gondwana new avalonia MyGame -o ./projects/MyGame
gondwana new avalonia MyGame --backbuffer gpu

`gondwana new blazor <name>`

If a .sln already exists in the output directory, adds the generated project to it; otherwise creates <name>.sln and adds the project.

Argument / Option	Short	Default	Description
`<name>`			Required. Name of the new project.
`--output <dir>`	`-o`		Directory to place the generated output in. Defaults to a new folder named `<name>` in the current directory.

Example

gondwana new blazor MyGame
gondwana new blazor MyGame -o ./projects/MyGame

Scaffolds a Blazor WebAssembly project targeting net8.0-browser for browser deployment. Includes Program.cs, App.razor, Pages/Index.razor, GameRenderSurface.razor (wrapping BlazorBitmapRenderSurfaceComponent), MyGameHost.cs, wwwroot/index.html, and the Gondwana.Blazor, Gondwana.Blazor.Hosting, and Gondwana.Audio.Browser package references. The gondwana-audio.js file is automatically included via the Gondwana.Audio.Browser NuGet package.

After scaffolding, start the Blazor dev server:

dotnet run

Build and publish for deployment:

dotnet workload install wasm-tools    # one-time per machine
dotnet publish -c Release

Output is placed in bin/Release/net8.0-browser/browser-wasm/AppBundle/.

📜 `gondwana run`

`gondwana run` (desktop)

Runs the desktop build of the project in the current directory.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--configuration <name>`	`-c`	`Debug`	Build configuration (`Debug`, `Release`).
`--framework <tfm>`	`-f`	(auto)	Target framework (e.g. `net8.0`). Required for multi-target projects.

Examples

gondwana run
gondwana run -p ./src/MyGame
gondwana run -c Release
gondwana run -f net8.0

Equivalent to dotnet run --project <path> -c <configuration>.

`gondwana run blazor`

Builds and runs the Blazor WebAssembly project in the browser.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--configuration <name>`	`-c`	`Debug`	Build configuration (`Debug`, `Release`).
`--skip-workload`		`false`	Skip `dotnet workload install wasm-tools`.

Examples

gondwana run blazor
gondwana run blazor -p ./src/MyGame
gondwana run blazor --skip-workload
gondwana run blazor --skip-workload -c Release

Equivalent to dotnet run --project <path> -c <configuration>. The Blazor dev server starts automatically and opens the game in the browser at the address printed to the console.

📜 `gondwana publish`

Subcommand	Description
(default)	Publish the desktop build of the current project.
`desktop`	Publish the desktop build of the current project.
`blazor`	Publish the current Blazor WebAssembly project for browser deployment.
`itch`	Package a browser/WASM AppBundle as an itch.io-ready zip.

`gondwana publish` / `gondwana publish desktop` (desktop default)

Publishes the desktop build of the project in the current directory.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--configuration <name>`	`-c`	`Release`	Build configuration (`Release`, `Debug`).
`--framework <tfm>`	`-f`	(auto)	Desktop target framework to publish. Required only when multiple non-browser target frameworks exist.
`--runtime <rid>`	`-r`	(none)	Runtime identifier such as `win-x64`, `linux-x64`, or `osx-arm64`.
`--output <path>`	`-o`	(dotnet default)	Publish output directory.
`--self-contained`		`false`	Publish as self-contained.
`--publish-single-file`		`false`	Publish as a single-file executable.

Equivalent to dotnet publish <path> -c <configuration> -f <framework> with optional -r <rid>, -o <path>, --self-contained, and /p:PublishSingleFile=true.

Examples

gondwana publish
gondwana publish -p ./src/MyGame
gondwana publish -r win-x64
gondwana publish -f net8.0 --self-contained
gondwana publish -r win-x64 --self-contained --publish-single-file

On success, the command prints the publish output directory as a plain line when it can be located.

`gondwana publish blazor`

Installs the wasm-tools .NET workload (unless --skip-workload) then runs dotnet publish -c Release and reports the published wwwroot path.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--configuration <name>`	`-c`	`Release`	Build configuration (`Release`, `Debug`).
`--skip-workload`		`false`	Skip `dotnet workload install wasm-tools`.

Examples

gondwana publish blazor
gondwana publish blazor -p ./src/MyGame
gondwana publish blazor --skip-workload -c Debug

On success, the command prints the AppBundle path as a plain line (bin/<Configuration>/net8.0-browser/browser-wasm/AppBundle/). If publish succeeds but the output cannot be located, a warning is printed.

For packaging or deployment, see also gondwana publish itch, gondwana deploy, and gondwana deploy itch.

`gondwana publish itch`

Publishes the project for net8.0-browser (unless --skip-build) and packages the AppBundle contents into an itch.io-ready zip with index.html at the zip root.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--configuration <name>`	`-c`	`Release`	Build configuration (`Release`, `Debug`).
`--output <path>`	`-o`	`bin/<Configuration>/net8.0-browser/browser-wasm/<ProjectName>-itch.zip`	Output zip path.
`--skip-build`		`false`	Skip the dotnet publish step and package an existing AppBundle.
`--skip-workload`		`false`	Skip `dotnet workload install wasm-tools`.

Examples

gondwana publish itch
gondwana publish itch -p ./src/MyGame
gondwana publish itch --skip-build
gondwana publish itch -o ./artifacts/MyGame-itch.zip

On success, the command prints the zip path as a plain line.

📜 `gondwana deploy`

Subcommand	Description
(default)	Deploy a Blazor WebAssembly publish output to a static web host.
`blazor`	Deploy a Blazor WebAssembly publish output to a static web host.
`itch`	Deploy a browser/WASM build to itch.io via `butler`.

`gondwana deploy` / `gondwana deploy blazor` (default)

Deploys the project for browser/WASM to a static web host.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--configuration <name>`	`-c`	`Release`	Build configuration (`Release`, `Debug`).
`--web-root <path>`		(none)	Local destination directory for the publish wwwroot contents.
`--remote-host <user@host>`		(none)	SSH remote, used with `--remote-path`.
`--remote-path <path>`		(none)	Remote destination path, used with `--remote-host`.
`--skip-build`		`false`	Skip the dotnet publish step and deploy an existing publish output.
`--skip-workload`		`false`	Skip `dotnet workload install wasm-tools`.
`--no-mirror`		`false`	Do not remove stale files from the destination (no mirroring). By default the destination is mirrored (stale files are deleted).
Specify either `--web-root` or `--remote-host` + `--remote-path`, not both.

Examples

gondwana deploy --web-root ./dist/MyGame
gondwana deploy -p ./src/MyGame --web-root ./dist/MyGame
gondwana deploy blazor --remote-host deploy@example.com --remote-path /var/www/html/mygame
gondwana deploy --skip-build --web-root ./dist/MyGame
gondwana deploy --web-root ./dist/MyGame --no-mirror

Remote deployment uses rsync -avz --delete (requires rsync on PATH). Pass --no-mirror to omit --delete.

After a successful deployment, the command reminds you of the HTTP headers your server must send on every response for .NET WASM threading (SharedArrayBuffer) to work:

Cross-Origin-Opener-Policy:   same-origin
Cross-Origin-Embedder-Policy: require-corp

The site must also be served over HTTPS.

On success, the command prints the deploy destination as a plain line: the absolute local path when using --web-root, or user@host:/remote/path/ when using --remote-host/--remote-path.

`gondwana deploy itch`

Publishes the project for net8.0-browser (unless --skip-build), packages the AppBundle, and uploads it to itch.io using butler.

Option	Short	Default	Description
`--project <path>`	`-p`	(current directory)	Path to the `.csproj` or its parent directory.
`--itch-game <user/game>`		(required)	The itch.io game slug.
`--itch-channel <name>`		`html5`	The itch.io release channel name.
`--configuration <name>`	`-c`	`Release`	Build configuration (`Release`, `Debug`).
`--skip-build`		`false`	Skip the dotnet publish step and deploy an existing AppBundle.
`--skip-workload`		`false`	Skip `dotnet workload install wasm-tools`.

Examples

gondwana deploy itch --itch-game user/mygame
gondwana deploy itch -p ./src/MyGame --itch-game user/mygame
gondwana deploy itch --itch-game user/mygame --itch-channel html5-beta
gondwana deploy itch --skip-build --itch-game user/mygame

Prerequisites:

butler on PATH
butler login already completed
the itch.io game already exists

On success, the command prints the game URL as a plain line (e.g. https://user.itch.io/game).

📜 `gondwana templates`

Subcommand	Description
`install`	Install `Gondwana.Templates`, or check for updates if already installed.
`update`	Check installed Gondwana templates for updates without downgrading newer local versions.
`list`	List installed Gondwana templates.

`gondwana templates install`

Installs Gondwana.Templates from NuGet when it is missing. If it is already installed, this command checks for template updates instead so a newer local package is retained. No arguments or options.

`gondwana templates update`

Runs dotnet new update. This checks installed template packages for updates without downgrading a newer already-installed local Gondwana.Templates package. No arguments or options.

`gondwana templates list`

Runs dotnet new list gondwana and prints matching templates. No arguments or options.

Asset type-map JSON format

The --type-map flag is optional. When omitted, assets pack (and pack) resolve the type config in this order, falling back to built-in defaults if nothing is found:

The path given to --type-map <file>
gondwana-asset-types.json in the current working directory
gondwana-asset-types.json next to the gondwana executable
Built-in defaults — no config file required

Drop a gondwana-asset-types.json in the project directory (or pass --type-map) to customise extension → type mappings for assets pack.

{
  "Image":  ["png", "jpg", "jpeg", "bmp", "gif", "webp", "tiff", "ico"],
  "Audio":  ["wav", "mp3", "ogg", "flac", "aac", "wma", "mid", "midi"],
  "Video":  ["mp4", "avi", "mkv", "mov", "wmv", "webm", "m4v"],
  "Cursor": ["cur", "ani"],
  "Font":   ["ttf", "otf", "woff", "woff2"],
  "Svg":    ["svg"]
}

Valid type names match the AssetTypes enum: Image, Audio, Video, Font, Cursor, Svg, Misc.

Gondwana CLI Cheatsheet

Installation

Top-level commands

📜 gondwana help

📜 gondwana doctor

📜 gondwana info

📜 gondwana assets

gondwana assets pack <source> <output>

gondwana assets list <file>

gondwana assets extract <file> <output>

gondwana assets generate-keys <file>

📜 gondwana pack

📜 gondwana new

gondwana new winforms <name>

gondwana new avalonia <name>

gondwana new blazor <name>

📜 gondwana run

gondwana run (desktop)

gondwana run blazor

📜 gondwana publish

gondwana publish / gondwana publish desktop (desktop default)

gondwana publish blazor

gondwana publish itch

📜 gondwana deploy

gondwana deploy / gondwana deploy blazor (default)

gondwana deploy itch

📜 gondwana templates

gondwana templates install

gondwana templates update

gondwana templates list

Asset type-map JSON format

Where to read next

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Gondwana Wiki

Introduction

Core Concepts

Rendering

Systems

Advanced Topics

Reference

Clone this wiki locally

📜 `gondwana help`

📜 `gondwana doctor`

📜 `gondwana info`

📜 `gondwana assets`

`gondwana assets pack <source> <output>`

`gondwana assets list <file>`

`gondwana assets extract <file> <output>`

`gondwana assets generate-keys <file>`

📜 `gondwana pack`

📜 `gondwana new`

`gondwana new winforms <name>`

`gondwana new avalonia <name>`

`gondwana new blazor <name>`

📜 `gondwana run`

`gondwana run` (desktop)

`gondwana run blazor`

📜 `gondwana publish`

`gondwana publish` / `gondwana publish desktop` (desktop default)

`gondwana publish blazor`

`gondwana publish itch`

📜 `gondwana deploy`

`gondwana deploy` / `gondwana deploy blazor` (default)

`gondwana deploy itch`

📜 `gondwana templates`

`gondwana templates install`

`gondwana templates update`

`gondwana templates list`