Commands and examples

Use ./build/csha from a build tree or csha after installation. Start with
Quick start for a complete walkthrough. The three command forms
are:

csha -M MODE [IMAGE_AND_MAP_OPTIONS]
csha blob-streams COMMAND [STREAM_OPTIONS]
csha docker-image COMMAND [DOCKER_OPTIONS]

Subcommands have their own parsers. Image flags such as -M, -p, and -o
do not configure Blob Streams or Docker image commands.

Choose a mode

Use the short name or its long alias with -M. The table describes the current
behavior, including modes that produce metadata rather than recovered files.

Mode	Alias	Input and behavior	Output / recovery
`f`	`full`	Ordinary path encodes `-P` using `-p`; with two `--key-image` values, encodes `-s` or `-f` instead	Environment PNG / `fd`
`fd`	`full-decode`	Read an environment map with matching credentials	Plaintext display; image-pair path supports exact file output with `-o`
`fz`	`full-zip`	Read `-z` archive into environment map(s)	Master map and, for larger inputs, companion chunks / `fdz`
`fdz`	`full-decode-zip`	Read a single map, master map with companion chunks, or legacy mosaic	Archive at `-Z`
`ens`	`encode-no-seed`	Encrypt `-P` with `-p`	AES PNG / `di` or `pd`
`ews`	`encode-with-seed`	Encrypt `-P`; optionally render the separate `-S` seed	Writes `encoded.png` plus the optional map
`es`	`encode-string`	Encrypt text from `-s`	AES PNG / `di` or `ds`
`ef`	`encode-file`	Read binary bytes from `-f` and encrypt	AES PNG / API for exact file output; `di` displays text
`ez`	`encode-zip`	Read and Base64-wrap an archive from `-z`	AES PNG / `dz`
`ds`	`decode-string`	Decode an AES image	Labeled plaintext on stdout
`di`	`decode-image`	Decode an AES image	Labeled plaintext on stdout
`dm`	`decode-map`	Read visible seed metadata	Seed, version, and spawn details
`dz`	`decode-zip`	Decode a ZIP AES image	Restored archive at required `-Z` path
`mfs`	`map-from-string`	Render numeric seed supplied by `-S`	Seed map PNG
`mfi`	`map-from-image`	Read a seed from image metadata, or hash the image with `-g`	Printed seed; `-G` also writes its map
`mfz`	`map-from-zip`	Encrypt an archive, then derive a seed from that image	Printed seed; does not preserve the archive in a generated seed map
`mts`	`map-to-string`	Read seed metadata	First seed and hex representation
`mti`	`map-to-image`	Read and save a map image	PNG copy, not decryption
`mtz`	`map-to-zip`	Export seed metadata via system `zip`	Metadata archive; legacy path
`pe`	`pure-encode`	Encrypt plaintext from `-P` using `-p`	AES PNG / `pd`
`pd`	`pure-decode`	Decode an AES image	Labeled plaintext on stdout

Use explicit -M: the default and unknown-mode fallback are f. -e and
-d add validation checks but do not change -M. See
Troubleshooting for known edge cases.

Image and map options

Option	Meaning
`-h`, `--help`	Show usage
`-v`, `--version`	Show the executable version
`-M`, `--mode MODE`	Select an image/map mode
`-s`, `--string TEXT`	Input text for `es` or image-pair `f`
`-f`, `--file PATH`	File input for `ef` or image-pair `f`
`-z`, `--zip PATH`	Archive input
`-i`, `--image PATH`	Input image, mutually exclusive with data URL input
`-o`, `--output PATH`	Generated image; decoded file output in image-pair `fd`
`-Z`, `--zip-output PATH`	Restored or exported ZIP path
`-p`, `--public-key VALUE`	Symmetric encryption-key input despite the historical name
`-P`, `--password VALUE`	Plaintext or environment password, depending on mode
`-A`, `--aes-mode MODE`	`GCM` (default), `CBC`, or `CTR`
`-k`, `--key-derive MODE`	`PBKDF2` (default), `DIRECT`, or `FIXED`
`-S`, `--seed VALUE`	Numeric Minecraft seed
`-m`, `--mc-version VALUE`	Project's Minecraft version selector; default `18`
`-a`, `--salt VALUE`	Image-to-seed salt; not the AES derivation salt
`-g`, `--gen-seed`	Hash input image to derive a seed
`-G`, `--gen-map`	Generate a map from the derived seed in `mfi` / `mfz`
`--image-data-url VALUE`	Literal PNG data URL or `@file`
`--data-url-output PATH`	Save a complete PNG data URL alongside supported image output
`--cipher NAME`	Choose AES or one of ten additional authenticated ciphers
`--list-ciphers`	List supported cipher names
`--key-image PATH`	Repeat twice to encode an image-password map; once to decode

Key and password semantics are explained in Formats and keys.
For new command examples, specify matching AES settings at both ends when
using non-default values. The FIXED derivation uses a built-in constant key.

Output behavior

Use explicit output paths in scripts. Ordinary es, ez, and pe default to
encoded.png; ef defaults to encoded_file.png; ordinary f defaults to
output.png; mfs defaults to map.png; image-pair f defaults to
pair-map.png. Ordinary image outputs may overwrite existing files.

di, ds, and pd print diagnostics plus a labeled plaintext value. Redirecting
stdout is not an exact binary file recovery interface. Use ez / dz for
archives, image-pair fd -o for its files, or the C++ API.
Blob Streams sends diagnostics to stderr and received bytes to stdout; Docker
PNG commands refuse to overwrite their key/archive/image outputs.

Use --cipher NAME to select one of ten non-AES authenticated algorithms;
--list-ciphers lists them. See encryption algorithms.

Text and files

./build/csha -M es -s "Hello World" -p example-key -o encoded.png
./build/csha -M di -i encoded.png -p example-key

./build/csha -M ef -f input.txt -p example-key -o file.png
./build/csha -M di -i file.png -p example-key

For ef, the decode command above demonstrates readable text only. For an
exact binary file recovery, choose the ZIP route below or the C++ API.

ZIP data

./build/csha -M ez -z archive.zip -p example-key -o archive.png
./build/csha -M dz -i archive.png -p example-key -Z restored.zip

Minecraft maps

./build/csha -M mfs -S 12345678 -m 18 -o map.png
./build/csha -M dm -i map.png

Keep generated images as PNGs to preserve the embedded pixel data. To derive a
seed and map from an arbitrary image:

./build/csha -M mfi -i input.png -g -G -o derived-map.png
./build/csha -M mfz -z archive.zip -p example-key -g -G -o zip-seed-map.png

No -S is needed for these derived seeds. A seed map retains the derived seed,
not the original image or archive bytes.

Ordinary environment maps

./build/csha -M f -P demo-message -p demo-key -o environment.png
./build/csha -M fd -i environment.png -P demo-message -p demo-key

Without image credentials, f currently encodes the -P value itself. It does
not read -s or -f as an independent payload. Use image-pair mode below for
those inputs, or the library's generate_env_map(data, password, key) API.
For a ZIP distributed across environment maps:

./build/csha -M fz -z archive.zip -P map-password -p example-key -o archive-map.png
./build/csha -M fdz -i archive-map.png -P map-password -p example-key -Z restored.zip
cmp archive.zip restored.zip

For larger inputs, keep archive-map.png together with archive-map.chunks/
and all its numbered chunk_0.png, chunk_1.png, … files. fdz finds the
companion directory from the master map's basename and restores chunks in
order. Missing or undecodable chunks fail recovery. Small inputs use one map.

Seed metadata row

Generated maps keep visible seed metadata entirely in the first row. If the
seed list exceeds the current width (more than 56 seeds at 512 pixels), the map
widens by a whole horizontal scale factor using nearest-neighbor sampling. No
seed entries are dropped, and the decoder still accepts older multi-row maps.
This applies to seed metadata, including the final map in a chunked ZIP export;
environment-map payloads still use low-order bits throughout the map.

Large-file encoding

AES images use a versioned binary pixel format with an explicit ciphertext
length. Encoding and decoding avoid per-pixel hex strings; library calls work
in memory instead of writing intermediate PNGs. The CLI still writes the
requested output image. ZIP payloads retain the existing Base64 convention.

The updated decoder reads legacy images as well as the new format. New AES
images require this updated decoder; older binaries do not understand the
length header. Existing legacy images whose ciphertext ended in zero retain
the old format's ambiguous padding limitation. PNG remains required.

Environment-map capacity checks now count four channels per encoded byte and
reject oversize payloads instead of silently truncating or returning raw
ciphertext pixels as a map. This is an in-memory optimization, not streaming;
large inputs still need memory proportional to their size.

Local Release-build check (2026-10-15, macOS, 8 MiB stored ZIP): encode plus
decode fell from 2.445 s to 0.317 s (about 7.7x). Both restored ZIPs matched the
original byte-for-byte. This is one local measurement, not a cross-machine
performance guarantee. Binary round-trip tests cover CBC, CTR, GCM, PNG reloads,
non-contiguous images, a trailing-zero ciphertext, and legacy format reads.

Base64 PNG data URLs

Export a generated image to a text file containing a complete data URL:

./build/csha -M es -s "Hello" -p example-key -o encoded.png --data-url-output encoded.url
./build/csha -M di --image-data-url @encoded.url -p example-key

--image-data-url also accepts a literal data:image/png;base64,... value.
Use @file for large images to avoid shell argument-size limits. Data URLs are
self-contained and do not upload an image or create a hosted HTTPS link. PNG
bytes and pixel values are preserved; malformed Base64 and other MIME types
are rejected. Multi-map ZIP modes do not support data URL output.

Either-image passwords

./build/csha -M f -s "secret data" --key-image first.png --key-image second.png -o pair-map.png
./build/csha -M fd -i pair-map.png --key-image first.png
./build/csha -M fd -i pair-map.png --key-image second.png

Use -f input.bin when encoding a file and -o restored.bin when decoding.
Both supplied images independently unlock the same payload. A random data key
encrypts the payload once; each image's SHA-256 digest separately wraps that
key. AES-GCM is the default for both operations; --cipher NAME selects an
alternative for both. Image filenames and file metadata are not keys:
dimensions and decoded BGR pixels are. Keep at least one original image for recovery;
resizing, editing or JPEG recompression changes the key. Anyone possessing
either image can unlock the map.

Pair maps have a distinct format, preserve their seed entry, require PNG, and
accept up to 196,432 plaintext bytes with AES or 196,288 with an alternative
cipher in one 512-by-512 map. Oversize input fails before generation. Pair mode
uses authenticated encryption and image-derived keys; -p, -A, and -k
do not configure its credentials. Older binaries cannot decode new pair formats.

Image-pair maps also support data URLs:

./build/csha -M f -s "secret data" --key-image first.png --key-image second.png -o pair-map.png --data-url-output pair-map.url
./build/csha -M fd --image-data-url @pair-map.url --key-image second.png

Blob Streams

csha blob-streams --help provides live encryption/decryption, device identities,
direct TCP and a paired HTTP CONNECT relay. See Blob Streams
for two-way communication examples and the C++ session API.

Docker image commands

csha docker-image has keygen, pack, inspect, restore, load, and run
commands. It streams a Docker-save archive into PNG pixels with a separate
binary encryption key. See Docker images as PNGs for the
complete workflow, available run options, and disk requirements.

Commands and examples

Choose a mode#

Image and map options#

Output behavior#

Text and files#

ZIP data#

Minecraft maps#

Ordinary environment maps#

Seed metadata row#

Large-file encoding#

Base64 PNG data URLs#

Either-image passwords#

Blob Streams#

Docker image commands#