Getting Started

Getting Started

wowlab is a personal project that runs from source on your own machine. There is no installer, no app store and no hosted version, by design.

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.)

Install

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	C:\Program Files (x86)\World of Warcraft, C:\Program Files\World of Warcraft, and the same folders under each fixed drive

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 prints how to point wowlab at yours, on every run.

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; --yes takes it without asking; --json never asks and takes nothing without --yes. With several flavors you choose one, 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.
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.

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). 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:

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

Next

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