Getting Started

Getting Started

wowlab is a personal project that runs on your own machine. There is no app store and no hosted version, by design. You can install a tagged release, or run it from source.

This wiki describes main. A release can lag behind it: a command named here may only be in a source checkout until the next release.

What you need

• uv, which brings Python 3.12 with it.
• A World of Warcraft install, to use the tools. (You do not need one to run the test suite: the tests use committed fixtures and none touches a real install.)

wowlab is developed on macOS. Windows and Linux are untested. There is no native Linux client, so a Linux install means Wine, Lutris or Proton, and wowlab finds it only when you point it there.

Install

From a release. The releases page carries the wheel, the sdist and SHA256SUMS. Install the wheel with uv tool install; the README has the exact line for the current release. Then run commands as wowlab ….

From source, to get everything on main:

git clone https://github.com/sandgraal/wowlab && cd wowlab
make setup
uv run wowlab --version

Every command below is run as uv run wowlab … from the checkout.

Point it at your install

wowlab looks in the usual places first:

Platform	Default locations searched
macOS	/Applications/World of Warcraft
Windows	On each drive, the system drive first: World of Warcraft at the top of the drive, then under Program Files (x86), then under Program Files
Linux	None: name the folder yourself

If yours is somewhere else (a Wine, Lutris or Proton prefix, or a custom folder on macOS), name the install root: the folder that contains the file .build.info.

export WOWLAB_WOW_ROOT="/path/to/World of Warcraft"

You can also pass --root PATH to any command; it wins over the environment variable. There are no credentials anywhere in the project.

When doctor finds no install, or --root or WOWLAB_WOW_ROOT names a folder that is not one, it lists where it looked and prints how to point wowlab at yours, on every run.

Inside the install, each flavor folder is a real folder named like _name_ that holds a .flavor.info file. A _..._ folder that is a link (a symlink, or a junction on Windows) is not followed and not taken as a flavor, even though the game reads through it. doctor and install show list such folders under "Folders named ... not taken as flavors", each with the reason, so back up the folder a link points to yourself. An install folder you reach through a link (the path you pass to --root, or one of its parents) is fine.

The first run

The first time you run wowlab doctor on an install (the snapshot store holds no snapshot of it yet), it does more than its usual report:

1. It says what wowlab will and will not do, including that doctor asks wago.tools about your versions unless you pass --offline.
2. It prints its usual report.
3. It shows what a first snapshot would hold, per flavor: size and an estimated time, links (never followed), folders that look synced by a cloud service, sync conflict copies and online-only files. It also says whether the game is running.
4. It offers the snapshot. It asks when you run it in a terminal (the default answer is no); --yes takes it without asking; --json never asks and takes nothing without --yes. When input is not a terminal and --yes is not given, it takes nothing and prints the command that would. With several flavors you choose one (pressing Enter takes none), or name it with --flavor (--yes alone then exits 2).
5. It takes the snapshot, labelled first run, into wowlab's own store, never into the install, and verifies the store. If other flavors are installed, it names each with the wowlab snap create --flavor command that snapshots it.
6. It ends with how to undo: the snapshot's id and the wowlab snap restore and wowlab undo commands.

The offer comes back on every run until the store holds a snapshot of this install. On a first run, doctor exits 3 if the write gate refuses the snapshot, and 1 if it fails or the store does not verify. The --json report has a first_run field, present only on a first run. When doctor finds problems, its text ends with a "Problems:" block that says why it exits 1.

Reporting a bug

wowlab doctor --redact prints a report safe to paste into an issue. Character, realm and account names, BattleTags, GUIDs, email addresses, your login and computer names, your home folder and journal labels become placeholders such as <CHARACTER>, <REALM>, <ACCOUNT> and <HOME>. Add --redact-name NAME (repeatable) for another name, such as your guild's; it implies --redact. --json works too and keeps the same shape.

A redacted run skips the first run: no snapshot is offered, and --yes or --flavor with --redact is a usage error (exit 2).

Your first five minutes

uv run wowlab doctor            # finds the install, its flavors and versions, whether the game runs
uv run wowlab install show      # the install root, its flavors and its .build.info rows
uv run wowlab tree --explain    # everything in a flavor folder, each path explained
uv run wowlab snap create -m "before I touch anything"
uv run wowlab snap list

doctor also reports your server-sync settings (synchronizeBindings, synchronizeMacros, synchronizeConfig). When those are on, the server can replace your local binds, macros or settings at login, which matters for anything that edits them. wowlab tells you when a setting is unset and says plainly that it does not know the client's default.

Add --offline to doctor to skip asking wago.tools whether each version is listed.

Tip

Take a snapshot first. It costs a few seconds, and wowlab undo and wowlab snap restore can only go back to something that was saved. Anything that writes into your install also takes its own snapshot automatically, but your own labelled one is the baseline you will actually reach for.

Things worth knowing up front

• Close the game before anything that writes. The write gate refuses while the client is running. The client rewrites its settings and SavedVariables files when you log out or /reload, so an outside edit made while the game runs is lost.
• Only some commands change your install. undo, snap restore, profile apply, sv merge and addon install / addon remove do, and every one goes through the write gate, shows a plan and asks first unless you pass --yes (most also take --dry-run). In wowlab ui they run first as a plan and change files only when you press Confirm. Everything else reads, or writes only to wowlab's own data folder. See the Command Reference.
• Everything has --json. Every command that reports something can print machine-readable JSON instead of text.
• Exit codes: 0 ok, 1 error, 2 usage, 3 refused by the write gate.

Where wowlab keeps its own data

In your platform's user data folder (~/Library/Application Support/wowlab/ on macOS, ~/.local/share/wowlab/ on Linux, %LOCALAPPDATA%\wowlab\wowlab\ on Windows), never inside the game install or the repository. wowlab doctor prints the exact path of the snapshot store, which is under store/ there.

What	Holds
snapshot store	every snapshot and profile, content-addressed and immutable, plus the journal of changes made through the write gate
game-table cache	tables downloaded from wago.tools, one copy per exact game version
saved looks	your customization looks, as JSON
generated pages	the local HTML page from wowlab looks page (the UI's Looks tab writes the same page)

Next

• Safety and Guarantees — what the write gate does and refuses
• Snapshots and Undo
• Command Reference