Repository navigation
Command Line Reference
Steve Whitley edited this page Nov 11, 2026
·
1 revision
Every command of distiller, generated from the tool's own help (distiller help <command>). For what the commands are for and how they fit together, see Using the command line.
Run the tool inside the app as /Applications/Distiller.app/Contents/Helpers/distiller, or swift run distiller from a checkout. --help works on every command, and --version prints the version. Set DISTILLER_HOME to a folder to keep experiments away from your real library and bottles.
-
distiller hw: Show this Mac's hardware fingerprint. -
distiller setup: Check what Distiller needs and install what's missing. -
distiller components: Manage Wine builds, graphics layers and winetricks. -
distiller bottles: List and create bottles. -
distiller run: Run a program in a bottle and wait for it to exit. -
distiller recipe: Create, check and submit recipes. -
distiller install: Install a game from a recipe file. -
distiller games: List the games in your library. -
distiller launch: Start a game and wait for it to exit. -
distiller community: Browse shared recipes and report results. -
distiller github: Sign in to GitHub to submit recipes. -
distiller storage: Show or change where Wine builds and bottles are kept. -
distiller mcp: Run a Model Context Protocol server so an assistant can help troubleshoot games. -
distiller assistant: Turn the AI troubleshooting assistant (distiller mcp) on or off, or show how to connect an AI app. -
distiller logs: Show how much the logs take, clean them up, or change how long and how much to keep. -
distiller app: Check for a newer Distiller, from the repository this copy was built from.
Show this Mac's hardware fingerprint.
USAGE: distiller hw [--json]
OPTIONS:
--json Print JSON instead of text.
Check what Distiller needs and install what's missing.
Subcommands:
-
status(the default): Show what's installed. -
install: Install Rosetta, Wine, winetricks, cabextract, DXMT or DXVK.
Show what's installed.
USAGE: distiller setup status
Install Rosetta, Wine, winetricks, cabextract, DXMT or DXVK.
D3DMetal can't be downloaded for you; import it with: distiller components
import-gptk <GPTK .dmg>
USAGE: distiller setup install [<items> ...] [--all] [--wine-build <wine-build>]
ARGUMENTS:
<items> rosetta, wine, winetricks, cabextract, dxmt or dxvk.
OPTIONS:
--all Install everything that's missing.
--wine-build <wine-build>
Wine build: wine-staging or wine-devel. (default:
wine-staging)
Manage Wine builds, graphics layers and winetricks.
Subcommands:
-
list(the default): List installed components. -
check: Look for newer Wine builds, graphics layers and winetricks. -
update: Install component updates, then remove versions nothing needs. -
use: Make an installed version the active one. -
clean: Remove component versions nothing needs any more. -
updates: Show or change how Distiller keeps components up to date. -
import: Import a folder or archive as a component. -
import-gptk: Import D3DMetal from your Game Porting Toolkit download.
List installed components.
USAGE: distiller components list
Look for newer Wine builds, graphics layers and winetricks.
USAGE: distiller components check
Install component updates, then remove versions nothing needs.
Without an id, installs every update except components you're keeping on an
older version (see 'distiller components use').
USAGE: distiller components update [<id>] [--keep-old]
ARGUMENTS:
<id> A component id from 'distiller components check',
such as wine-staging. Omit for all.
OPTIONS:
--keep-old Keep old versions even when nothing needs them.
Make an installed version the active one.
New games use the active version, and games that follow updates move to it.
Making an
older version active keeps that component there: automatic updates skip it
until you
make the newest version active again.
distiller components use wine-staging@11.21
USAGE: distiller components use <component>
ARGUMENTS:
<component> A component as id@version, from 'distiller components
list'.
Remove component versions nothing needs any more.
USAGE: distiller components clean [--dry-run]
OPTIONS:
--dry-run Only list what would be removed.
Show or change how Distiller keeps components up to date.
ask: check daily and show updates (the default). auto: install them by
themselves. off: don't check.
USAGE: distiller components updates [<mode>]
ARGUMENTS:
<mode> ask, auto or off. Omit to show the current setting.
(values: ask, auto, off)
Import a folder or archive as a component.
Examples:
distiller components import ~/Downloads/wine-11.0 --kind wine --id winehq
--family winehq --version 11.0
distiller components import ~/Downloads/winetricks --kind winetricks --id
winetricks --version 20260125 --arch universal
distiller components import ~/Downloads/dxmt --kind graphics --id dxmt
--version 0.70 --provides dxmt --placement wine_lib
USAGE: distiller components import <source> --kind <kind> --id <id> --version <version> [--arch <arch>] [--family <family>] [--provides <provides>] [--placement <placement>] [--executable <executable>] [--sha256 <sha256>] [--name <name>]
ARGUMENTS:
<source> A folder, or a .tar.xz, .tar.gz or .zip archive.
OPTIONS:
--kind <kind> wine, graphics or winetricks. (values: wine,
graphics, winetricks)
--id <id> A short identifier, such as winehq or dxmt.
--version <version> The component's version.
--arch <arch> x86_64, arm64 or universal. (values: x86_64, arm64,
universal; default: x86_64)
--family <family> For Wine builds: crossover, winehq or gptk.
--provides <provides> For graphics layers: d3dmetal, dxmt, dxvk or wined3d.
(values: d3dmetal, dxmt, dxvk, wined3d)
--placement <placement> For graphics layers: wine_lib or prefix_dlls.
(values: wine_lib, prefix_dlls)
--executable <executable>
Path of the main executable inside the component, if
not standard.
--sha256 <sha256> Expected SHA-256 of an archive.
--name <name> Display name.
Import D3DMetal from your Game Porting Toolkit download.
USAGE: distiller components import-gptk <path>
ARGUMENTS:
<path> The GPTK .dmg, its mounted volume, or a folder copied
from it.
List and create bottles.
Subcommands:
-
list(the default): List bottles. -
create: Create an empty bottle. -
drives: List a bottle's drive letters, or map a Mac folder's drive to the next free letter.
List bottles.
USAGE: distiller bottles list
Create an empty bottle.
USAGE: distiller bottles create <name> [--wine <wine>]
ARGUMENTS:
<name> A name for the bottle.
OPTIONS:
--wine <wine> Wine build to use, as id or id@version. Defaults to
the first installed.
List a bottle's drive letters, or map a Mac folder's drive to the next free letter.
USAGE: distiller bottles drives <bottle> [--map <map>]
ARGUMENTS:
<bottle> The bottle ID, from 'distiller bottles'.
OPTIONS:
--map <map> Map the drive that holds this folder (D:, then E:, …).
Run a program in a bottle and wait for it to exit.
Phase 0 test: distiller run <bottle-id> notepad
USAGE: distiller run <bottle> <program> [<arguments> ...]
ARGUMENTS:
<bottle> The bottle ID, from 'distiller bottles'.
<program> A program: a name Wine knows (notepad, winecfg,
regedit) or a path.
<arguments> Arguments passed to the program.
Create, check and submit recipes.
Subcommands:
-
validate: Check that recipe files are valid and safe. -
resolve: Show the settings a recipe resolves to on this Mac. -
inspect: Suggest recipe settings for a Windows program. -
create: Create a recipe, a bottle for it, and install the game. -
programs: List programs in a game's bottle. -
set-launch: Set the program a game's recipe launches. -
edit: Print the path of a game's editable recipe.yaml (then run 'distiller recipe reload'). -
reload: Apply an edited recipe.yaml to its game. -
run-installer: Run a Windows installer in a game's bottle and add it to the recipe. -
check-link: Check which installer links a player's Distiller can download directly. -
check-signature: Check a Windows installer's publisher signature (Authenticode). -
community-check: Prove a recipe works for other players before submitting it. -
submit: Submit a game's recipe to the community repository as a pull request.
Check that recipe files are valid and safe.
USAGE: distiller recipe validate <files> ...
ARGUMENTS:
<files> One or more recipe .yaml files.
Show the settings a recipe resolves to on this Mac.
USAGE: distiller recipe resolve <file>
ARGUMENTS:
<file> A recipe .yaml file.
Suggest recipe settings for a Windows program.
USAGE: distiller recipe inspect <exe>
ARGUMENTS:
<exe> The game's .exe.
Create a recipe, a bottle for it, and install the game.
Examples:
distiller recipe create --title "Example Game" --folder ~/Games/Example --exe
Example.exe
distiller recipe create --title "Example Game" --installer
~/Downloads/setup_example.exe
distiller recipe create --title "Example Game" --manual --graphics wined3d
Add --dry-run to print the recipe without installing.
USAGE: distiller recipe create --title <title> [--folder <folder>] [--exe <exe>] [--link] [--installer <installer>] [--manual] [--slug <slug>] [--id <id>] [--graphics <graphics>] [--winetricks <winetricks>] [--windows <windows>] [--dry-run]
OPTIONS:
--title <title> The game's title.
--folder <folder> A game folder already on this Mac.
--exe <exe> With --folder: the program to launch, relative to the
folder.
--link With --folder: link the folder instead of copying it.
--installer <installer> A Windows installer (.exe or .msi).
--manual An empty bottle; install things yourself afterwards.
--slug <slug> Game ID (defaults to one made from the title).
--id <id> Recipe ID (defaults to the graphics layer).
--graphics <graphics> d3dmetal, dxmt, dxvk or wined3d (defaults to what the
program suggests). (values: d3dmetal, dxmt, dxvk,
wined3d)
--winetricks <winetricks>
Winetricks verbs, comma-separated (adds to the
suggestions).
--windows <windows> Windows version, such as win10.
--dry-run Print the recipe and stop.
List programs in a game's bottle.
USAGE: distiller recipe programs <game>
ARGUMENTS:
<game> The game ID, from 'distiller games'.
Set the program a game's recipe launches.
USAGE: distiller recipe set-launch <game> <exe> [<arguments> ...]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
<exe> A Windows path such as 'C:\Games\Example\Game.exe'.
<arguments> Arguments for the program.
Print the path of a game's editable recipe.yaml (then run 'distiller recipe reload').
USAGE: distiller recipe edit <game>
ARGUMENTS:
<game> The game ID, from 'distiller games'.
Apply an edited recipe.yaml to its game.
USAGE: distiller recipe reload <game>
ARGUMENTS:
<game> The game ID, from 'distiller games'.
Run a Windows installer in a game's bottle and add it to the recipe.
USAGE: distiller recipe run-installer <game> <installer> [--no-record]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
<installer> The installer (.exe or .msi).
OPTIONS:
--no-record Don't add the installer to the recipe.
Check which installer links a player's Distiller can download directly.
Asks each link the way Distiller downloads installers, with no cookies and no
referrer (HEAD, or a 1-byte GET), in order, and reports the first that works.
Give the link you clicked first, then any it redirects to. Signed or expiring
links are skipped. The app's Get from Download Page… finds the links for you.
USAGE: distiller recipe check-link <links> ... [--size <size>]
ARGUMENTS:
<links> Installer links, the one you clicked first.
OPTIONS:
--size <size> The installer's size in bytes, if you know it: links
that serve a different size are rejected. (default: 0)
Check a Windows installer's publisher signature (Authenticode).
Verifies that the program is signed, unchanged since signing, by a code-signing
certificate macOS trusts, and prints the signer. Installers that change with
every update can be checked this way instead of with a fixed checksum.
USAGE: distiller recipe check-signature <file> [--signer <signer>]
ARGUMENTS:
<file> The installer (.exe or .msi).
OPTIONS:
--signer <signer> The signer it must be, such as "Example Publisher,
Inc.".
Prove a recipe works for other players before submitting it.
In a new bottle: downloads the game's official installer (game.installer.url;
with only a download page, game.installer.page, you download it in your browser
and give its path), applies the recipe's settings and starts the installer.
Follow its steps; when the game is running (started by the installer, or by you
from the list of installed programs) and has reached its login or menu, answer
y and choose its program. A pass is saved with the game; `distiller recipe
submit` then submits that checked recipe.
USAGE: distiller recipe community-check <game> [--keep-bottle]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--keep-bottle Keep the test bottle afterwards (it's removed by
default).
Submit a game's recipe to the community repository as a pull request.
Sign in first with: distiller github login
USAGE: distiller recipe submit <game> [--tier <tier>] [--fps <fps>] [--notes <notes>] [--description <description>] [--genres <genres>] [--year <year>] [--developer <developer>] [--confirm]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--tier <tier> Include a report: platinum, gold, silver, bronze or
borked. (values: platinum, gold, silver, bronze,
borked)
--fps <fps> Average frames per second, for the report.
--notes <notes> Notes for the report.
--description <description>
For a game new to the catalogue: a short description,
in your own words.
--genres <genres> For a new game: genres, comma-separated (action,
adventure, mmo, rpg, strategy, …).
--year <year> For a new game: its release year.
--developer <developer> For a new game: its developer.
--confirm Confirm the recipe only downloads the publisher's
official installer, and that you license it under MIT.
Install a game from a recipe file.
Supply files and folders the recipe asks for with --file <id>=<path> and
--folder <id>=<path>, for example --file installer=~/Downloads/setup.exe. A
file the recipe has you download from its publisher's page (user_download) is
asked for if you don't give it: download it in your browser, then enter its
path. Distiller checks it's the file the recipe expects.
USAGE: distiller install <recipe> [--file <file> ...] [--folder <folder> ...] [--link]
ARGUMENTS:
<recipe> A recipe .yaml file.
OPTIONS:
--file <file> A file for a user_file or user_download step, as
id=path.
--folder <folder> A folder for a user_folder step, as id=path.
--link Link user_folder folders instead of copying them.
List the games in your library.
Subcommands:
-
list(the default): List the games in your library. -
link-folder: Use a game's original folder instead of the copy in its bottle. -
icon: Show, read, or set a game's icon. -
versions: Show or choose the Wine build, graphics layer and winetricks a game uses. -
restore: Show a game's restore point (its bottle from before it moved to a newer Wine), or act on it. -
rebuild: Rebuild a game's bottle with the current components, or decide on a rebuild.
List the games in your library.
USAGE: distiller games list
Use a game's original folder instead of the copy in its bottle.
Compares the copy with the original first. Without --apply it only reports.
With --apply it deletes the copy, links the original into the bottle and maps
its drive. Files that exist only in the copy (often saves or settings) block
--apply unless you also pass --discard-copy-changes.
USAGE: distiller games link-folder <game> <folder> [--step <step>] [--apply] [--discard-copy-changes]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
<folder> The original game folder.
OPTIONS:
--step <step> The user_folder step ID, when the recipe has more
than one.
--apply Delete the copy and link the original.
--discard-copy-changes Apply even though the copy has files the original
doesn't.
Show, read, or set a game's icon.
Without options, reads the icon from the game's program again and prints where
it's saved.
USAGE: distiller games icon <game> [--set <set>] [--reset]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--set <set> Use this image, .icns, .ico, or another program's
(.exe) icon instead.
--reset Go back to the icon read from the game's program.
Show or choose the Wine build, graphics layer and winetricks a game uses.
A game follows the active version of each (see 'distiller components'), or
stays on one you
choose. Staying keeps a working game as it is when the others update, but it
may miss fixes
or break with newer recipes. Wine can only stay on the build the game's bottle
uses now or a
newer one.
distiller games versions <game> --wine wine-staging@11.21
distiller games versions <game> --wine follow
USAGE: distiller games versions <game> [--wine <wine>] [--graphics <graphics>] [--winetricks <winetricks>]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--wine <wine> id@version to stay on, or 'follow'.
--graphics <graphics> id@version to stay on, or 'follow'.
--winetricks <winetricks>
id@version to stay on, or 'follow'.
Show a game's restore point (its bottle from before it moved to a newer Wine), or act on it.
How long restore points are kept: settings.json restore_point_days (default 7;
0 until you confirm the game works; -1 until you remove it).
USAGE: distiller games restore <game> [--works] [--rollback] [--discard]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--works The game works on its new Wine: remove the restore
point (unless you keep them until removed).
--rollback Put the restore point back and keep the game on the
Wine it was on.
--discard Remove the restore point.
Rebuild a game's bottle with the current components, or decide on a rebuild.
Installs the game's recipe into a new bottle with the active Wine build,
graphics layer and
winetricks, then switches the game to it; the old bottle is kept until you
decide (--keep
moves it to the Trash, --switch-back returns to it). Files and folders the
recipe asked for
are reused from the old bottle where possible; supply others with --file /
--folder id=path.
Anything the game keeps inside its bottle (saves under C:\users, settings, a
launcher's
sign-in) isn't carried over.
USAGE: distiller games rebuild <game> [--keep] [--switch-back] [--file <file> ...] [--folder <folder> ...]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--keep Keep the rebuilt bottle and move the old one to the
Trash.
--switch-back Go back to the old bottle and remove the rebuilt one.
--file <file> A file for a user_file or user_download step, as
id=path.
--folder <folder> A folder for a user_folder step, as id=path.
Start a game and wait for it to exit.
USAGE: distiller launch <game> [--diagnose] [--dll <dll> ...] [--args <args>] [--graphics <graphics>]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--diagnose For this launch only: log DLL loads, exceptions and
Wine errors, and show Apple's Metal HUD while the
game draws with Metal. Nothing is saved to the recipe.
--dll <dll> For this launch only, override a DLL, such as
nvapi64=disabled or d3dcompiler_47=native. Repeat for
more.
--args <args> For this launch only, use these program arguments
instead of the recipe's (one string; "" for none).
--graphics <graphics> For this launch only, use this graphics layer:
d3dmetal, dxmt, dxvk or wined3d. (values: d3dmetal,
dxmt, dxvk, wined3d)
Browse shared recipes and report results.
Subcommands:
-
refresh: Download the latest recipe index. -
search: Search the downloaded index, ranked for this Mac. -
report-link: Print a pre-filled GitHub link for reporting how a game ran.
Download the latest recipe index.
USAGE: distiller community refresh
Search the downloaded index, ranked for this Mac.
USAGE: distiller community search <query>
ARGUMENTS:
<query> Words in the game's title.
Print a pre-filled GitHub link for reporting how a game ran.
USAGE: distiller community report-link <game> --tier <tier> [--fps <fps>] [--notes <notes>]
ARGUMENTS:
<game> The game ID, from 'distiller games'.
OPTIONS:
--tier <tier> platinum, gold, silver, bronze or borked. (values:
platinum, gold, silver, bronze, borked)
--fps <fps> Average frames per second, if you measured it.
--notes <notes> Anything others should know.
Sign in to GitHub to submit recipes.
Subcommands:
-
login: Sign in with a one-time code. -
logout: Forget the saved GitHub token. -
status(the default): Show who you're signed in as.
Sign in with a one-time code.
USAGE: distiller github login
Forget the saved GitHub token.
USAGE: distiller github logout
Show who you're signed in as.
USAGE: distiller github status
Show or change where Wine builds and bottles are kept.
The library, logs and settings always stay in the support folder. A drive's
root gets a Distiller folder.
Subcommands:
-
show(the default): Show storage locations and their drives. -
move: Move Wine builds or bottles to another folder or drive.
Show storage locations and their drives.
USAGE: distiller storage show
Move Wine builds or bottles to another folder or drive.
Copies across drives, then removes the originals. Quit the app and stop any
games first.
USAGE: distiller storage move <kind> <folder>
ARGUMENTS:
<kind> What to move: wine or bottles. (values: wine, bottles)
<folder> The destination folder. A drive's root gets a
Distiller folder.
Run a Model Context Protocol server so an assistant can help troubleshoot games.
Speaks MCP over standard input and output; an MCP client starts it. The tools
only read: games, recipes, launch logs, the game's own logs, program inspection
and this Mac's setup. The assistant is off until you turn it on (distiller
assistant on); `distiller assistant setup` shows how to connect other clients.
Claude Code: claude mcp add distiller -- <path to distiller> mcp
Claude Desktop: add to claude_desktop_config.json under "mcpServers":
"distiller": { "command": "<path to distiller>", "args":
["mcp"] }
USAGE: distiller mcp
Turn the AI troubleshooting assistant (distiller mcp) on or off, or show how to connect an AI app.
on / off take effect at once, even for an assistant that's already connected.
The assistant is off until you turn it on.
Distiller doesn't change other apps' settings: add `<path to distiller> mcp` to
your AI
app's MCP servers and it starts Distiller's server when it needs it.
setup [client] prints how, with this command's path:
claude-desktop, claude-code, chatgpt, lm-studio, ollama, other.
USAGE: distiller assistant [<action>] [<client>]
ARGUMENTS:
<action> status, on, off or setup. (default: status)
<client> For setup: the client to explain (default: all of
them).
Show how much the logs take, clean them up, or change how long and how much to keep.
Distiller's app cleans up when it starts and once a day: logs older than the
retention period, then the oldest over the size limit. Logs written in the last
hour are always kept.
Subcommands:
-
show(the default): Show the logs' size and the cleanup settings. -
clean: Remove old logs now, then the oldest over the size limit. -
set: Change how long and how much to keep (0 turns either off).
Show the logs' size and the cleanup settings.
USAGE: distiller logs show
Remove old logs now, then the oldest over the size limit.
USAGE: distiller logs clean
Change how long and how much to keep (0 turns either off).
USAGE: distiller logs set [--keep-days <keep-days>] [--limit-mb <limit-mb>]
OPTIONS:
--keep-days <keep-days> Remove logs older than this many days (0 keeps them).
--limit-mb <limit-mb> Keep at most this many megabytes of logs, removing
the oldest first (0 means no limit).
Check for a newer Distiller, from the repository this copy was built from.
Subcommands:
-
check(the default): Say whether a newer Distiller is available. -
download: Download the latest Distiller.dmg and check it, without installing it.
Say whether a newer Distiller is available.
USAGE: distiller app check
Download the latest Distiller.dmg and check it, without installing it.
Checks the release's checksum, and that the app is signed by the same developer
as this copy and notarized. Installing (which replaces the app) is done from
the app's Settings ▸ Updates, or by opening the disk image.
USAGE: distiller app download [--to <to>]
OPTIONS:
--to <to> Where to save Distiller.dmg (default: ~/Downloads).
Distiller is open source under the MIT licence · Website · Releases · Report a problem. Game names, icons and screenshots belong to their publishers.
Getting started
Playing
Recipes
Keeping things working
Command line