mz-toolkit 🧰

A handy command-line toolkit with everyday utilities — fully offline, no API keys required.

Installation

Install via npm:

npm install -g @emzett-digital/mz-toolkit

Help

Use --help or -h to see the available commands and options. If a command is used incorrectly, mz prints the error and automatically shows the relevant help.

mz --help
mz image crop --help
mz image crop photo.png

Commands

🔐 Password generator

mz pw                     # Default: 16 characters
mz pw -l 24               # Length 24
mz pw -c 5                # Generate 5 passwords at once
mz pw --no-symbols        # Without special characters

#️⃣ Hash

Creates a hash digest (one-way — not reversible).

mz hash "MyPassword" SHA-256
mz hash "MyPassword" MD5
mz hash "MyPassword"              # Default: SHA-256

Available algorithms: mz algos

🔎 Dehash

Attempts to reverse a hash via dictionary lookup (only works if the plaintext is in the list — hashing is fundamentally not directly reversible).

mz dehash <hash> SHA-256
mz dehash <hash> SHA-256 --wordlist my-list.txt

🔒 Encrypt

Encrypts text symmetrically (reversible with a password).

mz encrypt "Secret text" AES-256          # Password is auto-generated
mz encrypt "Secret text" AES-256 -p my-password
mz encrypt "Secret text"                  # Default: AES-256-GCM

🔓 Decrypt

mz decrypt "<token>" -p my-password

📋 List algorithms

mz algos

📱 QR code

mz qr "https://example.com"
mz qr "Hello World" --small
mz qr "https://example.com" --output example.png --format png

Read a QR code from a local image file or a direct image URL:

mz qr-read my-qr.png
mz qr-read "https://example.com/qr-code.jpg"
mz qr-read my-qr.png --json

The decoder prints the URL or text stored in the QR code. qr-decode is an alias for qr-read. Remote images are limited to 100 MB and only HTTP(S) URLs are accepted.

For local files, --file can be used explicitly. If no source or --file is provided, mz opens a native file picker with single-file selection:

mz qr-read --file my-qr.png
mz qr-read
mz image convert --file photo.png --output photo.webp --lossless
mz image crop --resolution 1920x1080 --output wallpaper.png

The picker uses Windows File Explorer dialogs, zenity/kdialog on Linux, and the macOS file chooser. A source argument and --file cannot be used together.

🖼️ Image tools

Convert an image selected from your own files, or download an image from a direct http:// or https:// URL. The output format is inferred from the destination extension unless --format is provided.

# Local file to lossless WebP
mz image convert photo.png --output photo.webp --lossless

# Local file to JPEG with quality 95
mz image convert photo.tiff --output photo.jpg --quality 95

# Download and convert a direct image URL
mz image download "https://example.com/image.png" --output image.webp --lossless

# Convert a URL directly without a separate download step
mz image convert "https://example.com/image.png" --output image.tiff --lossless

# Crop to an exact resolution; upscales proportionally first when necessary
mz image crop photo.png --resolution 1920x1080 --output wallpaper.webp --lossless

# Choose which part remains when the aspect ratios differ
mz image crop photo.png --resolution 800x800 --position north --output avatar.png

Options:

• --output <file>: Destination path; required for both commands.
• --format <format>: Explicit output format; otherwise inferred from the file extension.
• --lossless: Enables lossless encoding where the target format supports it.
• --quality <number>: Quality for formats that support quality settings, from 1 to 100.
• --resolution <width>x<height>: Exact crop size; required by image crop.
• --position <position>: Crop anchor (centre, north, south, east, or west).

Cropping never stretches an image. If the requested resolution is larger than the source, the image is proportionally upscaled with Sharp's Lanczos resampling and then cropped to the exact target size. Upscaling cannot restore detail that was not present in the original image, but it avoids distortion and uses the best available resampling quality.

Supported formats depend on the installed sharp/libvips build and include PNG, JPEG/JPG, WebP, AVIF, GIF, TIFF, JP2, JXL, HEIF, and HEIC. JPEG/JPG cannot be lossless; use PNG, TIFF, WebP, AVIF, or JXL when lossless output is required. Website downloads follow redirects, accept files up to 100 MB, and only allow HTTP(S) URLs.

📏 Unit converter

mz convert 100 km mi
mz convert 20 c f
mz convert 5 kg lb

Supports: length (mm, cm, m, km, in, ft, yd, mi), weight (mg, g, kg, t, oz, lb), temperature (c, f, k)

🔤 Base64

mz b64 encode "Hello World"
mz b64 decode "SGVsbG8gV29ybGQ="

📄 Format/validate JSON

mz json data.json
mz json data.json --write   # Write formatted result back to file

⏱️ Timer

mz timer 25 --label "Pomodoro"
mz timer 0.5              # 30 seconds

✅ To-do list

mz todo add Buy groceries
mz todo list
mz todo done 1
mz todo remove 1

🔌 Port scanner and port management

Scan local ports, list open ones, and close or block ports.

mz ports scan 127.0.0.1 1 1024
mz ports status localhost 1 1024
mz ports close 3000 tcp
mz ports block 8080 tcp
mz ports unblock 8080 tcp

Features:

• scan a host/port range for open ports
• show currently open local ports
• close the process behind a port
• block or unblock a port via the Windows firewall

Note: firewall blocking is currently implemented for Windows systems.

🕵️ Network sniffer

Listen for incoming traffic on a local TCP port and print connection payloads.

mz sniffer 3000 --host 127.0.0.1
mz sniffer 8080 --host 0.0.0.0 --max-connections 5
mz sniffer 9000 --raw

Use this for local debugging of services that accept plain TCP connections.