Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Simple and scriptable tools for Minecraft server admins. Read my blog post for the full story.

Download your world from Realms


This downloads the latest backup of your currently active world to world.tar.gz. No local install of Minecraft is needed. You're now free to run Overviewer or whatever you want.

You'll need

You need httpie and jq, so sudo apt-get install httpie jq if needed.

Validate your current access token

When you login, your access token is displayed and stored in the environment variable access_token. The token means you don't have to keep logging in (and risk rate-limiting), but eventually it expires. You can validate your access token at any time with

$ $access_token

Understanding logins

We run the login script with source to set three environment variables for the other tools to pick up:

  • access_token, e.g. 14fc1a392727462fa35e0d82e138aef1
  • name, e.g. notch
  • id, e.g. 069a79f444e94726a5befca90e38aaf5

If you're interested in player UUIDs check out

Rate limiting

If you made too many authentication requests recently, a valid login will be rejected as invalid - the error looks like an incorrect password. If in doubt, wait 15 minutes.

Notice, as long as $access_token shows your token is valid, you don't need to authenticate again.

Download an older backup

Pass the backup number 1-4, e.g. 2 downloads the second backup in the list. Default is 1.


  • Only the currently active world is available.
  • Only the four most recent backups are available for download.

Why did I make this?

As an admin I want small, simple tools that are easy to understand and adapt for my purposes.

There are amazing tools out there like yggdrasil, but they carry a ton of baggage (i.e. 67 npm packages).

The point of REST APIs is to be simple and accessible without advanced tools. For these scripts you just need httpie and jq, which deserve a place in your toolbox.

Understanding Realms

The backups listed in the game client are the only backups that exist. The 'download latest' button just selects the one at the top - #1, as indexed by the API - downloads it and extracts into your $HOME/.minecraft/saves with the correct world name.

You can see the same backup list in raw JSON with GET ${realms_server}/worlds/${world_id}/backups.

Service availability

I've seen the Realms API throw 503s - with the response Retry again later - on retrieving the download link for a world. Keep retrying until it works.


Each backup has a timestamp. When you download a world, check the timestamp on level.dat - this should match what's shown in the game client.

If you 'download latest' from the game,, what ends up in your saves directory is not identical to what you get direct from the API. I believe the game client processes the world files somehow, since many of their timestamps are set to now.


No releases published


No packages published