CLI Usage and Training

CLI Usage & Training

The moezip command-line executable provides tools for compressing text, decompressing archives, decoding hex strings directly in the terminal, and training custom router matrices on domain-specific text corpora.

---

Command Overview

moezip COMMAND [options]

Command	Alias	Description
compress	c	Compresses a text file or input string into a .moe binary archive.
decompress	d	Decompresses a .moe archive back into plain text.
hexdec	hd	Decompresses a hex-encoded string directly from the command line.
train	t	Trains the 32x32 state router transition matrix on a text dataset.

---

Global Options & Flags

Flag	Description	Default
-o, --output FILE	Specifies output file path (- outputs to stdout).	Auto-generated
--vocab FILE	Path to a custom vocabulary wordlist on disk.	words_final.txt (or embedded)
--router FILE	Path to a custom router state JSON file on disk.	router_stateless_v4.json (or embedded)
--corpus FILE	Input text corpus file (required for train command).	None
-q, --quiet	Mutes informational logs and progress metrics.	False

---

Command Reference & Examples

1. File Compression (compress / c)

Compresses a text file to a .moe archive:

# Basic compression
moezip compress input.txt -o archive.moe

# Mute diagnostic output
moezip compress input.txt -o archive.moe --quiet

2. File Decompression (decompress / d)

Restores a .moe binary archive to its original plain text:

# Basic decompression
moezip decompress archive.moe -o restored.txt

# Decompress to stdout stream
moezip decompress archive.moe -o -

3. Direct Hex Decoding (hexdec / hd)

Decompresses a hex-encoded string payload without saving an intermediate .moe file:

moezip hexdec 880A090A20202020414243... -o restored.txt

---

Stream Piping (stdin / stdout)

moezip supports I/O redirection using - as the input or output filename. Diagnostic logs are routed to stderr to keep stdout clean for binary data transfers.

On Windows platforms, standard input and output streams are automatically initialized in binary mode (_O_BINARY) to prevent newline translation (0x0A to 0x0D 0x0A) from corrupting binary compressed streams.

# Compress string from standard input and pipe to file
echo "Sample text to compress." | moezip compress - -o archive.moe

# Pipe decompressed output directly to another command
moezip decompress archive.moe -o - | grep "SearchTerm"

---

Training a Custom Domain Router Matrix (train / t)

moezip uses a $32 \times 32$ Markov transition matrix to predict word expert movements. By default, it includes pre-trained weights for general English text.

If you are compressing specialized domains (such as medical records, legal documents, or source code), you can train a custom router matrix to improve compression ratios.

Training Workflow

Step 1: Run Training on Corpus

Feed a raw text corpus (.txt) to the train command:

moezip train --corpus path/to/domain_corpus.txt --router router_stateless_v4.json

This processes the corpus tokens and saves the updated state transitions to router_stateless_v4.json.

Step 2: Embed New Weights into Source Code

Run make.py to convert the updated router_stateless_v4.json into C++ array chunks in embedded_assets.hpp:

python make.py

Step 3: Recompile Binaries

Rebuild the executable to generate a self-contained binary containing your domain-specific weights:

# Windows
cmake --build build --config Release

# Linux
cmake --build build_linux --parallel