Skip to content
Grapple

Documentation

Grapple on the command line

Grapple is a Mac app. Underneath it is a single shell script, grapple, that does all the real work — and you can run it yourself for scripting, automation, or just to watch exactly what happens.
On this page
  1. What the CLI is
  2. Where the binary lives
  3. Requirements
  4. The documentation
  5. Recipes

What the CLI is

Everything Grapple does — installing an engine, creating a Windows environment, setting up Steam, launching a game, collecting a diagnostics report — is one command in a bash script called grapple. The Mac app is a window onto that script: it runs the same commands you can run, and reads the same --json output documented here.

The app is the normal way to use Grapple. You never need the command line to play a game. Reach for it when you want to automate something, script a setup across machines, drive Grapple from another tool, or see the exact command and the exact error behind a failure.

One piece of vocabulary before you start: the CLI calls each isolated Windows environment a bottle, the old Wine term, and it prints that word in its own help and arguments. Everywhere else — in the app, on this site, and in the prose below — it is a Windows environment, or just an environment. Where you see <bottle> in a synopsis, type the name of an environment.

Where the binary lives

The script is bundled inside the app, at the path below. It is the same file for everyone — there is no separate CLI download and nothing to keep in sync.

/Applications/Grapple.app/Contents/Resources/grapple

To type grapple instead of that path, add an alias to your shell profile (~/.zshrc on a default macOS setup):

alias grapple="/Applications/Grapple.app/Contents/Resources/grapple"

Or put a symlink on your PATH, which also works from scripts and other tools:

sudo ln -s "/Applications/Grapple.app/Contents/Resources/grapple" /usr/local/bin/grapple

A symlink is safe: the script resolves its own real location before looking for the files that sit next to it (the Steam helper it installs, for one), so it finds them inside the app bundle either way. Check it with grapple version, which prints the version and nothing else:

$ grapple version
grapple 0.1.0

The app and the CLI share one data directory

Environments you create in Terminal show up in the app, and the other way round. Both read and write ~/Library/Application Support/Grapple unless you point them somewhere else — see the data directory.

Requirements

  • macOS. The script refuses to run anywhere else: grapple: grapple only runs on macOS.
  • Rosetta 2 on Apple Silicon. Windows games are x86, so every command except doctor stops immediately without it: grapple: Rosetta 2 is required: softwareupdate --install-rosetta --agree-to-license. Run that command once and you are done. Grapple is built for Apple Silicon; Intel Macs are not supported.
  • Disk space. An engine is a few hundred megabytes; games are what they are. grapple doctor warns below 10 GB free.

The documentation

Short version: the command reference has every command, flag and error message; configuration has the settings keys, the environment variables the script reads and the layout of the data directory; troubleshooting covers doctor, diagnostics reports and logs.

Recipes

Four things people actually do, end to end.

Install Steam and play a game

Create an environment, install Steam into it, and let Steam install the game. The first command downloads the default engine if you do not have it yet; the second downloads Valve's installer, runs it silently and applies the fix for Steam's black window.

$ grapple create games
==> Creating bottle 'games' with grapple-wine (first boot takes a minute)
==> Bottle ready: /Users/you/Library/Application Support/Grapple/bottles/games/prefix/drive_c

$ grapple steam games
==> Downloading Steam installer
==> Installing Steam (silent)
==> Running steam.exe in 'games' (log: …/bottles/games/logs/steam.exe.log)

Sign in to Steam in the window that opens and install your game as you would on a PC. When it is installed, Grapple can see it by name, straight from Steam's own manifests:

$ grapple programs games
steam:1374490    RuneScape: Dragonwilds

Start it from the Steam window, or hand Steam the app ID yourself. Anything you pass after the environment name goes to steam.exe unchanged:

$ grapple steam games -applaunch 1374490

Give a new game a few minutes on its first run: shaders are being compiled and cached, and it stutters until that settles.

Make a Mac launcher for a game

grapple shortcut writes a small double-clickable app into ~/Applications that runs one command. Pass steam to launch the Steam client, or the path of a program inside the environment — a macOS path or a C:\ path both work. The last argument names the app.

$ grapple shortcut games steam
==> Created /Users/you/Applications/Steam.app

$ grapple shortcut games "C:\Program Files (x86)\Steam\steam.exe" "Dragonwilds"
==> Created /Users/you/Applications/Dragonwilds.app

Drag it to your Dock. If you later rename the environment, grapple rename rewrites the launchers it made so they keep working.

Find and move a game's saves

Saves live in the Windows user profile inside the environment. grapple userdir prints its macOS path, so you can hand it straight to another command:

$ grapple userdir games
/Users/you/Library/Application Support/Grapple/bottles/games/prefix/drive_c/users/you

$ open "$(grapple userdir games)/Documents/My Games"

Most games keep saves under Documents/My Games, AppData/Roaming or AppData/LocalLow in that folder. To move them between environments, quit the game first, then copy the game's folder across:

$ cp -R "$(grapple userdir old-games)/Documents/My Games/Some Game" \
       "$(grapple userdir games)/Documents/My Games/"

The profile is named after your macOS account on the default engine and crossover on CrossOver-derived ones, which is why it is worth asking the CLI rather than guessing. If an environment has more than one profile, grapple userdir games --all lists them, the one in use first.

Try a different graphics layer

If a game crashes on startup, renders nothing, or runs far slower than it should, the DirectX-to-Metal layer is the first thing to change. auto picks D3DMetal when it is installed and DXMT otherwise; you can pin any of them.

$ grapple set games graphics d3dmetal
==> games: graphics=d3dmetal

$ grapple info games
Bottle:  games
C drive: /Users/you/Library/Application Support/Grapple/bottles/games/prefix/drive_c
Logs:    /Users/you/Library/Application Support/Grapple/bottles/games/logs
Settings:
  engine=grapple-wine
  winver=win10
  esync=on
  msync=on
  avx=on
  retina=off
  graphics=d3dmetal

Changing graphics stops everything running in that environment and rebuilds its Windows registry, so quit your game first. grapple unset games graphics puts it back on auto. Which layer suits which game is explained in the graphics setting and, at more length, in the DirectX on Mac guide.