Download this page as .mdz

Using the mdz CLI

mdz is the MDZip command line: create, inspect, validate, and edit .mdz archives from a terminal or a script. Self-contained builds for Windows, macOS, and Linux — no runtime to install.

Install

Windows (WinGet):

winget install MDZip.Cli

Windows (PowerShell), or macOS/Linux, if you'd rather not use a package manager — review the script before running it, same as any install-by-URL command:

irm https://raw.githubusercontent.com/mdzip-project/mdzip-cli/main/scripts/install.ps1 | iex
curl -fsSL https://raw.githubusercontent.com/mdzip-project/mdzip-cli/main/scripts/install.sh | sh

Check the install worked:

mdz info

Create and inspect

# Package a folder of markdown + images into an archive
mdz create my-notes -o my-notes.mdz --title "My Notes"

# List the contents as a tree
mdz ls my-notes.mdz

# Manifest, sizes, entry point, mode — the overview
mdz inspect my-notes.mdz

# Print a packaged file to stdout
mdz cat my-notes.mdz index.md

Validate

mdz validate my-notes.mdz

Reports valid, warning (e.g. no manifest), or errors. A well-formed producer's output validates without warnings.

Edit an archive in place

# Add or replace a file (archive path, then the local source file)
mdz add my-notes.mdz assets/logo.png ./logo.png

# Remove a file
mdz remove my-notes.mdz assets/old-photo.jpg

# Read or update manifest metadata
mdz manifest get my-notes.mdz
mdz manifest set my-notes.mdz --title "Renamed Notes" --description "Now with a description"

Assets and workspaces

# List packaged assets with kinds and MIME types
mdz assets my-notes.mdz

# Workspace summary: title, mode, entry point, document count
mdz workspace inspect my-notes.mdz

mdz assets understands both Markdown image syntax and raw HTML <img> references when detecting orphaned assets.

Readable Git diffs

Git treats an .mdz as binary. mdz textconv (version 2.1.0 or later) prints an archive as text, so git diff shows what changed in each document inside it:

echo "*.mdz diff=mdz" >> .gitattributes
git config diff.mdz.textconv "mdz textconv"

Commit the .gitattributes line; each clone runs the git config line once. Using MDZip with Git, GitHub and Azure DevOps covers the rest: when to commit an .mdz at all, merges, and checking files in CI.

Extract

mdz extract my-notes.mdz -o ./my-notes-extracted

Or skip the CLI entirely: rename the file to .zip and use any archive tool — an .mdz is a standard ZIP.

Scripting notes

  • Commands exit non-zero on failure, so they compose in CI and scripts.
  • mdz validate before distributing is the golden rule — see the AI Producer Guide if the producer is an automated tool.

Source, releases, and issues: mdzip-project/mdzip-cli.

This page renders from cli.mdz (MDZip, ~4 KB, updated 2026-11-12) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.