mpqcli

A command-line tool to create, add, remove, list, extract, read, and verify MPQ archives using the StormLib library.

⚠️ Warning: This project is under active development and will change functionality between released versions until version 1.0.0.

Overview

This is a command-line tool, designed for automation and built with the Unix philosophy in mind. It is designed to work seamlessly with other command-line tools, supporting piping, redirection, and integration into shell scripts and workflows. For example:

• Run one command to create an MPQ archive from a directory of files or a single file
• Run one command to list all files in an MPQ archive
• Pipe the output to grep or other tools to search, filter, or process files
• Redirect output to files or other commands for further automation

If you require an MPQ tool with a graphical interface (GUI) and explicit support for more MPQ archive versions — I would recommend using Ladik's MPQ Editor.

Download

Precompiled Binaries

Pre-built binaries are available for Linux and Windows.

Linux/WSL:

curl -fsSL https://raw.githubusercontent.com/thegraydot/mpqcli/main/scripts/install.sh | bash

Microsoft Windows:

irm https://raw.githubusercontent.com/thegraydot/mpqcli/main/scripts/install.ps1 | iex

Check the latest release with binaries.

Docker Image

The Docker image for mpqcli is hosted on GitHub Container Registry (GHCR). It provides a lightweight and portable way to use mpqcli without needing to build or download a binary.

To download the latest version of the mpqcli Docker image, run:

docker pull ghcr.io/thegraydot/mpqcli:latest

You can run mpqcli commands directly using the Docker container. For example:

docker run ghcr.io/thegraydot/mpqcli:latest version

To use local files in the container, mount a directory from your host system. In the following example, the -v argument is used to mount the present working directory to /data directory in the container. Then the mpqcli container runs the list subcommand with /data/example.mpq as the target MPQ archive.

docker run -v $(pwd):/data ghcr.io/thegraydot/mpqcli:latest list /data/example.mpq

Subcommands

The mpqcli program has the following subcommands:

• version: Print the tool version number
• about: Print information about the tool
• info: Print information about MPQ archive properties
• create: Create an MPQ archive from a target directory or a single file
• add: Add a file to an existing MPQ archive
• remove: Remove a file from an existing MPQ archive
• list: List files in a target MPQ archive
• extract: Extract one/all files from a target MPQ archive
• read: Read a specific file to stdout
• verify: Verify a target MPQ archive signature

Command Examples

Many of the examples use the MPQ archive file, named wow-patch.mpq, from a original (Vanilla) World of Warcraft patch file, named WoW-1.10.0-to-1.10.1-enGB-patch.zip. If you want to replicate these examples, you can download the wow-patch.mpq file from the Internet Archive.

Print information about an MPQ archive

The info subcommand prints a list of useful information (property keys and values) of an MPQ archive.

$ mpqcli info wow-patch.mpq
Archive size: 1798918
File count: 65
Format version: 1
Header offset: 0
Header size: 32
Max files: 128
Signature type: Weak

Print one specific MPQ archive property

The info subcommand supports the following properties:

• archive-size
• file-count
• format-version
• header-offset
• header-size
• max-files
• signature-type

You can use the -p or --property argument with the info subcommand to print just the value of a specific property. This can be useful for automation, for example, to determine the signature type of a directory of MPQ archives.

$ mpqcli info -p file-count wow-patch.mpq
65

Create an MPQ archive from a target directory

Create an MPQ file from a target directory. Automatically adds (listfile) to the archive, and will skip this file if it exists in the target directory.

$ mpqcli create <target_directory>

The default mode of operation for the create subcommand is to take everything from the "target" directory (and below) and recursively add it to the archive. The directory structure is retained. Windows-style backslash path separators are used (\), as per the observed behavior in most MPQ archives.

Create an MPQ archive for a specific game

Target a specific game version by using the -g or --game argument. This will automatically set the correct archive format version and settings, although they can be overridden.

$ mpqcli create -g starcraft <target_directory>
$ mpqcli create --game wow-wotlk --sector-size 16384 --version 3 <target_directory>    # World of Warcraft - Wrath of the Lich King, but with non-standard sector size and MPQ version

Create an MPQ archive from a single file

Create an MPQ file from a single file.

$ mpqcli create --game diablo2 <target_file>

This will put the given file in the root of the MPQ archive. By optionally providing a path in the --name-in-archive parameter, the name that the file has in the MPQ archive can be changed, and it can be put in a directory.

Create and sign an MPQ archive

Use the -s or --sign argument to cryptographically sign an MPQ archive with the Blizzard weak signature.

$ mpqcli create --version 1 --sign <target_directory>

Create an MPQ archive with a given locale

Use the --locale argument to specify the locale that all added files will have in the archive. Note that subsequent added files will have the default locale unless the --locale argument is specified again.

$ mpqcli create <target_directory> --locale koKR

Add a file to an existing archive

Add a local file to an already existing MPQ archive.

$ echo "For The Horde" > fth.txt
$ mpqcli add fth.txt wow-patch.mpq
[+] Adding file: fth.txt

Alternatively, you can add a file under a specific file name using the -f or --filename-in-archive argument.

$ echo "For The Alliance" > fta.txt
$ mpqcli add fta.txt wow-patch.mpq --filename-in-archive "alliance.txt"
[+] Adding file: alliance.txt

Alternatively, you can add a file to a specific subdirectory using the -d or --directory-in-archive argument.

$ echo "For The Swarm" > fts.txt
$ mpqcli add fts.txt wow-patch.mpq --directory-in-archive texts
[+] Adding file: texts\fts.txt

Alternatively, you can add a file under a specific directory and filename using the -p or --path argument.

$ echo "For The Swarm" > fts.txt
$ mpqcli add fts.txt wow-patch.mpq --path "texts\swarm.txt"
[+] Adding file: texts\swarm.txt

To overwrite a file in an MPQ archive, set the w or --overwrite flag:

$ echo "For The Horde" > allegiance.txt
$ mpqcli add allegiance.txt wow-patch.mpq
[+] Adding file: allegiance.txt
$ echo "For The Alliance" > allegiance.txt
$ mpqcli add allegiance.txt wow-patch.mpq
[!] File already exists in MPQ archive: allegiance.txt - Skipping...
$ mpqcli add allegiance.txt wow-patch.mpq --overwrite
[+] File already exists in MPQ archive: allegiance.txt - Overwriting...
[+] Adding file: allegiance.txt

Add a file to an MPQ archive with a given locale

Use the --locale argument to specify the locale that the added file will have in the archive. Note that subsequent added files will have the default locale unless the --locale argument is specified again.

$ mpqcli add allianz.txt wow-patch.mpq --locale deDE
[+] Adding file for locale deDE: allianz.txt

Add a file with game-specific properties

Target a specific game version by using the -g or --game argument. This will automatically set the correct encryption rules and MPQ flags, although they can be overridden.

$ mpqcli add khwhat1.wav archive.mpq --game wc2   # In StarCraft and Warcraft II MPQs, wav files are compressed in ADPCM form
[+] Adding file: khwhat1.wav

Remove a file from an existing archive

Remove a file from an existing MPQ archive.

$ mpqcli remove fth.txt wow-patch.mpq
[-] Removing file: fth.txt

Remove a file from an MPQ archive with a given locale

Use the --locale argument to specify the locale of the file to be removed.

$ mpqcli remove alianza.txt wow-patch.mpq --locale esES
[-] Removing file for locale esES: alianza.txt

List all files in an MPQ archive

Pretty simple, list files in an MPQ archive. Useful to "pipe" to other tools, such as grep (see below for examples).

$ mpqcli list wow-patch.mpq
BM_COKETENT01.BLP
Blizzard_CraftUI.xml
CreatureSoundData.dbc
...
Blizzard_CraftUI.lua
30ee7bd3959906e358eff01332cf045e.blp
realmlist.wtf

List all files with detailed output

Similar to the ls command with the -l and -a options, additional detailed information can be included with the list subcommand. The -a option includes printing "special" files used in MPQ archives including: (listfile)