ddb-scraper

Turns the D&D Beyond content you own into a readable, offline library of files on your own computer.

What it is

ddb-scraper is a small personal tool you run on your own machine. You sign in with your own D&D Beyond account, and it downloads the rules content your account has access to and writes it out as ordinary readable text files in a folder you choose.

It also exports your own D&D Beyond characters into that same folder, so your characters sit right alongside the rules they use.

This is a tool for one person — you — running on your own computer. It is not a website, and it is not a service anyone else connects to.

What you get

Every spell is its own file. Every monster is its own file. Every class, subclass, species, background, feat, piece of equipment, and magic item — each gets its own file too. Files are grouped into folders by kind.

Each file starts with a small block of structured details — things like source book, level, school, or challenge rating — so entries can be filtered and sorted. Related entries link to each other: a class page points at its spells, and a monster points at its gear.

Index files are generated so you, or a tool, can navigate without opening everything one by one. The files open fine in any plain text editor and in note apps like Obsidian — nothing here is locked in a proprietary format.

What you can do with it

• Look things up offline. No page loads, no internet connection required, just open a file.
• Search across everything you own at once, with ordinary text search — no need to remember which book a rule lives in.
• Point Claude Code at the folder so it can find and cite the actual rules you own, instead of you copying and pasting rules text into a conversation, and instead of it guessing. For example, you could ask "which of my prepared spells can I cast without expending a spell slot?" and get an answer grounded in your actual, owned rules text.
• Keep your characters alongside the rules. A character's spells, gear, species, class, and feats link straight through to the matching entries in the library.

Good to know

• It only reaches content your own account has access to. It is not a way to get books you have not bought.
• The generated folder is rebuilt from scratch every time you run it. Treat it as throwaway output, and keep your own notes somewhere else.
• A full run covers thousands of entries and takes a while. It goes deliberately steadily rather than hammering D&D Beyond, and you can stop it and pick up where it left off.
• Your D&D Beyond sign-in value is stored encrypted on your machine and is never written out in readable form.

Personal use only

This exists so one person can read, offline, the content they already paid for. It is not for sharing, publishing, republishing, or redistributing that content in any form. Do not commit the generated library to a public repository or pass it to anyone else. All the game content it downloads remains the property of its publisher.

License

The source code in this repository is MIT licensed — see the LICENSE file. That license covers the code only. The D&D Beyond content this tool downloads is not the project's to license, and stays subject to the restriction stated directly above.

Getting started

1. Install the .NET 10 runtime/SDK.
2. From the repository folder, run dotnet run --project DdbScraper.Service. It opens in your browser automatically; if it does not, visit http://localhost:5101.
3. Go to Settings and paste your D&D Beyond session cookie value, then save. This is the value your browser already holds after you log in to D&D Beyond, and it is what lets the tool read your account's content as you. Set your output folder here too — this is where your library gets written.
4. Go to Sources to untick any books you do not own. Everything is included by default, and books you buy later are picked up automatically.
5. Go to Scrape, choose what to pull down, and start the run. Progress is shown live, you can cancel at any point, and closing or refreshing the browser tab does not kill a run in progress.
6. Go to Characters to pick which of your characters to export.

Run it in Docker

If you would rather not install the .NET runtime, you can run ddb-scraper in a container instead.

The short version:

1. Download docker-compose.yml into an empty folder on your machine.

2. From that folder, run:

   docker compose up -d

3. Open http://127.0.0.1:7080 in your browser.

What persists, and where. Two locations hold everything that matters between restarts:

• A Docker volume named ddb-scraper-appdata holds your settings, your book selections, and your encrypted D&D Beyond sign-in value.
• A folder next to the compose file, ./output, is where your library gets written. It is an ordinary folder on your machine — you can point it wherever you like by editing the ./output:/data/output line in the compose file. The small index database that keeps track of what has been scraped lives inside this same folder, which is why the folder stays a single portable unit.

This application has no sign-in of its own. It is built for one person on one machine. The supplied setup deliberately publishes it only to 127.0.0.1:7080 — the local machine — so nothing else on your network can reach it. If you change that (bind it to another address, forward the port, or put it on a server other people can reach), anyone who can reach it can read and replace your stored D&D Beyond sign-in value and start scrapes as you. If you want it reachable from elsewhere, put a reverse proxy that requires its own authentication in front of it; the application will not do that for you.

Output folder, inside a container. Leave the output folder setting as the supplied docker-compose.yml configures it. A path saved through the Settings page takes precedence over the container's own configuration, and saving a path from your own machine there would point the application at a folder that does not exist inside the container.

Stopping it:

docker compose down

Adding -v to that command also removes the named volume — which deletes your stored D&D Beyond sign-in value along with everything else on it.

Portable download

If you would rather not install anything at all — not even Docker — download a portable build instead.

What it is. Each release publishes one archive per platform: ddb-scraper-<version>-win-x64.zip for Windows and ddb-scraper-<version>-linux-x64.zip for Linux. Everything the application needs is inside the archive, so there is nothing to install first. Releases live on this repository's Releases page.

How to start it. Unzip the archive anywhere you have write access, then run the launcher inside it rather than the DdbScraper.Service executable directly — run.cmd on Windows, run.sh on Linux. On Linux, if the tool you used to unzip the archive did not preserve the executable bit, set it yourself first: chmod +x run.sh.

Why there is a launcher at all. The application is packed into a single file and unpacks itself the first time it runs. The folder it unpacks into is chosen before the application's own code starts, so the application cannot choose it — the launcher does, setting it to a folder next to the executable. What you will actually see: a folder named extracted appears beside the executable the first time you run it. That is normal, and deleting the whole unzipped folder removes everything cleanly.

If you would rather run the executable directly, set DOTNET_BUNDLE_EXTRACT_BASE_DIR yourself before launching it, pointing it at a folder beside the executable; the launcher exists so you don't have to.

The portable build stores its settings and encrypted D&D Beyond sign-in value in the usual per-user application-data location for your platform, not inside the unzipped folder, so upgrading by replacing the folder does not lose them.

Where things end up

your-output-folder/
├── classes/
├── subclasses/
├── species/
├── backgrounds/
├── feats/
├── equipment/
├── magic-items/
├── spells/
├── monsters/
└── characters/

Index files sit at the root of the output folder and inside each of the folders above. Pointing Claude Code at this folder is the whole point.