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 (PowerShell):

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

Linux / macOS:

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

A WinGet package (MDZip.Cli) is coming soon. 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.

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 — one self-contained file. Download it, open it in the web editor, or read how these pages are made.

Using the mdz CLI