Command reference

Every command and option in WinBridge 0.4.0, with the config file, environment variables, file locations and exit codes.

Global options

These go with any command, for example winbridge --verbose build.

Option	What it does
-v, --verbose	Prints every command, resolved path and tool line.
--version	Prints the WinBridge version.
-h, --help	Prints help. winbridge help <command> shows help for one command.

Commands at a glance

Command	What it does
winbridge build	Builds a project for Windows.
winbridge detect	Reports the project type found in a folder.
winbridge doctor	Checks which toolchains are available; installs components.
winbridge run	Runs a Windows executable on Linux.
winbridge prefix	Lists, deletes and adds runtimes to per-app prefixes.
winbridge package	Builds a Windows installer from built files.
winbridge desktop	Adds or removes desktop launcher entries.
winbridge recipe	Looks up and applies compatibility recipes.
winbridge report	Prints a hardware and compatibility report.
winbridge vm	Checks the Windows VM, runs VM apps, lists USB devices.

build

winbridge build [directory] [-- extra tool arguments]

Builds the project in directory (default: the current folder).

Option	What it does	Default
-o, --output	Folder the result is written to.	build/winbridge/<target> in the project
--target	Windows architecture: windows-x64 or windows-arm64.	windows-x64
--toolchain	Forces a toolchain by id instead of the first one that claims the project.	Automatic
--debug	Builds unoptimized, with debug information.	Off

Everything after -- is passed to the underlying compiler unchanged.

Every .exe and .dll that a build reports is checked for a valid 64-bit x86 Windows (PE32+) header. A build whose output fails that check is reported as failed.

Toolchain ids

Id	Builds	Needs
go	Go	go
rust	Rust	cargo, x86_64-w64-mingw32-gcc; rustup is optional
dotnet	.NET	dotnet
c	C/C++, MinGW ABI	zig, or x86_64-w64-mingw32-gcc / x86_64-w64-mingw32-g++
msvc	C/C++, MSVC ABI	clang, lld-link, and the msvc component
vm	Flutter	ssh, rsync, and a configured Windows VM

Naming a toolchain that cannot build the project type is an error, not a silent fallback.

How a project is detected

WinBridge looks at the given folder only. The first match in this order wins.

Order	Marker	Type
1	pubspec.yaml with a Flutter dependency	Flutter
2	go.mod	Go
3	Cargo.toml	Rust
4	*.csproj or *.fsproj	.NET
5	CMakeLists.txt, a Makefile, or *.c/*.cpp files	C/C++

detect

winbridge detect [directory]

Prints the project name, type, folder, the file that decided the type, and the toolchain that would build it. Builds nothing.

doctor

winbridge doctor
winbridge doctor --install <component>

Without options, lists the tool search path, the runtime for winbridge run, the installable components and every toolchain's requirements. Exits with code 1 when a required tool is missing.

Marker	Meaning
ok	Found. The path follows.
absent	An optional tool is not present.
MISSING	A required tool is not present.

Installable components

Component	Download	What it is
go	67 MB	Go toolchain, for Go projects.
zig	56 MB	Zig, used as the C/C++ cross-compiler.
nsis	2 MB	NSIS, used by winbridge package.
msvc	3 MB, then about 1–2 GB	xwin, plus the Microsoft CRT and Windows SDK it downloads.

In the Installable components list, managed means WinBridge downloaded and verified the component, system means a copy already on your machine is being used, partial means an unfinished install, and absent means it is not installed.

Where tools are searched

First match wins:

1. The folder named by WINBRIDGE_TOOLCHAIN_DIR.
2. WinBridge's managed installs in ~/.cache/winbridge/toolchains/.
3. Your PATH, in its own order. Relative PATH entries are skipped.

run

winbridge run <app.exe> [-- arguments for the app]

Option	What it does	Default
--prefix	Which app prefix to use.	The file name without .exe
--dxvk	Renders Direct3D through Vulkan. Remembered for the prefix.	Off
--no-dxvk	Turns DXVK off again for the prefix.

The exit code of winbridge run is the app's exit code.

prefix

Command	What it does
winbridge prefix list	Lists prefixes with their DXVK version and path.
winbridge prefix delete <name>	Deletes a prefix and everything in it, without asking.
winbridge prefix tricks <name> <verb> [verb...]	Runs winetricks verbs against a prefix.

package

winbridge package [directory]

Option	What it does	Default
-o, --output	Installer file to write.	<app>-<version>-setup.exe in the artifacts folder
--artifacts	Folder holding the built files.	build/winbridge/windows-x64 in the project
--script	NSIS script to use instead of the generated one.	None
--app-version	Version recorded in the installer.	0.0.0
--sign	PKCS#12 certificate (.pfx) to sign the installer with.	None

desktop

Command	What it does
winbridge desktop add <app.exe>	Adds a launcher entry. --name sets the display name, --prefix the prefix; both default to the file name without .exe.
winbridge desktop list	Lists the entries WinBridge created.
winbridge desktop remove <name>	Removes one entry that WinBridge created.

recipe

Command	What it does
winbridge recipe list	Lists bundled and user recipes.
winbridge recipe show <file.exe>	Fingerprints an installer and shows which recipe matches.
winbridge recipe apply <file.exe>	Applies the matching recipe. --prefix names the prefix.

report

winbridge report

Prints a filled-in hardware report: operating system and kernel, CPU, GPU, Vulkan, the Wine runtime and prefix state, and which toolchains are ready. The command sends nothing anywhere. It leaves out your host name, user name and paths under your home folder. Paste it into a hardware report issue if you choose to share it.

vm

Command	What it does
winbridge vm status	Checks that the VM answers and has Flutter. Accepts --accept-new.
winbridge vm doctor	Checks local ssh and rsync, the config, connectivity, and Flutter and rsync on the VM. Accepts --accept-new.
winbridge vm app <remote-exe-path>	Shows a program installed on the VM as a window, through FreeRDP. --sound redirects audio.
winbridge vm usb list	Lists USB devices on this machine. --all includes hubs.
winbridge vm usb passthrough <vendor:product>	Prints VM configuration for passing one USB device through. Changes nothing.

--accept-new trusts a VM host key seen for the first time. It never accepts a key that changed.

The VM config file

~/.config/winbridge/vm.json:

{
  "host": "localhost",
  "port": 2222,
  "user": "winbridge",
  "identityFile": "~/.ssh/id_winbridge_vm",
  "remoteWorkspace": "C:/winbridge"
}

Field	Required	Default	Rules
host	Yes		Letters, digits, ., _, -
port	No	22	1 to 65535
user	Yes		Letters, digits, ., _, -
identityFile	No	SSH's own default	No spaces; ~ is expanded
remoteWorkspace	Yes		Letters, digits, :, /, _, ., -; no ..; must exist on the VM
flutterPath	No	flutter on the VM's PATH	Same as remoteWorkspace

Environment variables

Variable	What it does
WINBRIDGE_WINE	Full path to a wine binary to use instead of the managed runtime.
WINBRIDGE_TOOLCHAIN_DIR	Folder of toolchains searched before everything else, laid out as <dir>/<toolchain>/bin/.
WINBRIDGE_VM_CONFIG	Path to a VM config file, used instead of vm.json.
WINBRIDGE_SIGN_PASSPHRASE	Certificate passphrase for package --sign.
WINBRIDGE_RECIPES_DIR	Folder of bundled recipes.
WINBRIDGE_RDP_ASK	Reserved. vm app stops with an error while it is set.
WINEDLLOVERRIDES	Your own Wine DLL overrides. They are kept and take priority over the ones WinBridge adds for DXVK.
XDG_CACHE_HOME, XDG_DATA_HOME, XDG_CONFIG_HOME	Move the cache, data and config folders below.

File locations

What	Where	Safe to delete?
Build output	build/winbridge/<target>/ in the project	Yes
Compiler caches	~/.cache/winbridge/build/	Yes
Managed compilers	~/.cache/winbridge/toolchains/	Yes; reinstall with doctor --install
Wine, DXVK, winetricks, NSIS	~/.cache/winbridge/runtimes/	Yes; downloaded again when needed
Microsoft CRT and Windows SDK	~/.cache/winbridge/xwin/	Yes; a 1–2 GB download to restore
App prefixes	~/.local/share/winbridge/prefixes/	Only if you no longer need the app's data
Your recipes	~/.local/share/winbridge/recipes/	They are your files
Launcher entries	~/.local/share/applications/winbridge-*.desktop	Use winbridge desktop remove
VM config	~/.config/winbridge/vm.json	It is your file

Pinned component versions

WinBridge 0.4.0 downloads these exact versions and checks each against a built-in SHA-256 checksum.

Component	Version
Wine	11.14 (64-bit, wow64 build)
DXVK	3.0.2
winetricks	20260125
Go	1.26.5
Zig	0.16.0
NSIS	3.12
xwin	0.9.0

The Microsoft CRT and Windows SDK are not pinned. They come from Microsoft at the version xwin selects.

Exit codes

Code	Meaning
0	Success.
1	A build, tool or check failed. Also returned by doctor, vm status and vm doctor when they find a problem.
2	The command line was wrong: unknown option, missing argument, a folder that does not exist.
141	The program reading WinBridge's output closed the pipe, as with winbridge doctor piped into head.
Other	winbridge run returns the exit code of the Windows app. winbridge vm app returns the FreeRDP client's.

Next steps

• Beginner guide
• Troubleshooting and FAQ