NeoZip CLI

Full-featured command-line ZIP application with blockchain integration and advanced compression

Release Notice

Current version: v0.90.0. This release adds full AES-256 encryption support. See CHANGELOG.md for details.

• API Stability: Command-line interface is becoming more stable but may still change
• Testing: Please test thoroughly and report any issues
• Feedback: We welcome feedback and bug reports via GitHub Issues or email [email protected]

Overview

NeoZip CLI is a modern, full-featured ZIP utility that provides:

• Standard ZIP Compatibility: ~99% compatible with InfoZip utilities
• Blockchain Integration: Tokenize archives and verify integrity on-chain
• Advanced Compression: Zstd, Deflate, and Store compression methods
• Encryption Support: AES-256 (default) and PKZIP encryption
• Cross-Platform: Works on macOS, Linux, and Windows

Features

Core Functionality

• ✅ Create, extract, and list ZIP archives
• ✅ Standard ZIP format compatibility
• ✅ ZIP64 support for large files (>4GB)
• ✅ Archive comments and file comments
• ✅ Recursive directory processing
• ✅ Pattern-based file inclusion/exclusion
• ✅ Stdin filename input

Compression

• Zstd: Modern, fast compression (default)
• Deflate: Standard ZIP compression (maximum compatibility)
• Store: No compression (fastest, for already-compressed files)
• Compression levels: 0-9 (0=store, 9=best compression)

Encryption

• AES-256: Strong encryption (default, recommended)
• PKZIP: Legacy encryption (for compatibility only)
• Password-protected archives
• Auto-detection of encryption method during extraction

Blockchain Features

• Tokenization: Create on-chain tokens for archives
• OpenTimestamp: Bitcoin blockchain timestamping
• Zipstamp: Ethereum blockchain timestamping (Zipstamp server)
• Integrity Verification: Verify archive integrity on-chain
• Network Support: Base Sepolia, Base Mainnet, Arbitrum, and more

Advanced Features

• Symbolic link handling
• Hard link detection and deduplication
• File permission preservation
• Progress reporting
• Archive integrity testing
• Update and freshen modes
• Move files into archive
• Delete files from archive

Installation

Prerequisites

• Node.js 16.0.0 or higher
• npm or yarn package manager

Install from npm

npm install -g neozip-cli

After installation, the following commands will be available:

• neozip - Create and manage ZIP archives
• neounzip - Extract files from ZIP archives
• neolist - List contents of ZIP archives

Verify Installation

neozip --version
neounzip --version
neolist --version

Quick Start

Basic Usage

# Create a ZIP archive
neozip archive.nzip file1.txt file2.txt folder/

# Create archive with recursive directory inclusion
neozip -r archive.nzip ./project/

# Create tokenized archive (blockchain integration)
neozip -b tokenized.nzip file1.txt file2.txt

# Extract files from archive
neounzip archive.nzip tests/extracted/

# Extract and verify tokenized archive
neounzip -t tokenized.nzip

# Test the archive file
neounzip -t archive.nzip

# List archive contents
neolist archive.nzip

# List with detailed information
neolist -v archive.nzip

Compression Examples

# Compress with default settings (Zstd)
neozip output.nzip ./src/

# Compress with maximum compression
neozip -9 output.nzip ./src/

# Compress with deflate (maximum compatibility)
neozip --compression deflate output.nzip ./src/

# Store files without compression (fastest)
neozip -0 output.nzip ./src/

Encryption Examples

# Create AES-256 encrypted archive (default, will prompt for password)
neozip -e secure.nzip file.txt

# Create AES-256 encrypted archive with password
neozip -e -P "mypassword" secure.nzip file.txt

# Explicitly use AES-256
neozip --aes256 -P "mypassword" secure.nzip file.txt

# Use legacy PKZIP encryption (weak, for compatibility only)
neozip --pkzip -P "mypassword" legacy.nzip file.txt

# Extract encrypted archive (auto-detects AES-256 or PKZIP)
neounzip -P "mypassword" secure.nzip tests/extracted/

Blockchain Examples

# Tokenize archive on Base Sepolia (default)
neozip -b tokenized.nzip file.txt

# Tokenize with OpenTimestamp proof (Bitcoin)
neozip -ots timestamped.nzip file.txt

# Create Zipstamp timestamp (Ethereum)
neozip -ts zipstamp.nzip file.txt

# Upgrade pending Zipstamp timestamp to confirmed
neozip upgrade zipstamp.nzip [output.nzip] [--wait]

# Extract and verify blockchain integrity
neounzip tokenized.nzip tests/extracted/

Commands

neozip - Create and Manage Archives

Create, update, and manage ZIP archives.

Basic Syntax:

neozip [options] <archive> [files...]

Common Options:

• -r, --recurse - Include subdirectories recursively
• -0 to -9 - Compression level (0=store, 9=best)
• -x, --exclude <pattern> - Exclude files matching pattern
• -i, --include <pattern> - Include only matching files
• -e, --encrypt - Encrypt files with AES-256 (default, will prompt for password)
• -P, --password <pwd> - Encrypt with password
• --aes256 - Use AES-256 encryption (default, recommended)
• --pkzip - Use legacy PKZIP encryption (weak, for compatibility only)
• -b, --blockchain - Enable blockchain tokenization
• -ots, --opentimestamp - Enable OpenTimestamp proof (Bitcoin)
• -ts, --timestamp - Enable Zipstamp timestamp (Ethereum)
• --timestamp-email <email> - Email for Zipstamp server (some servers require verified email)
• -T, --test-integrity - Test archive after creation
• -v, --verbose - Enable verbose output
• -q, --quiet - Suppress output

Configuration Commands:

neozip init      # Interactive wallet setup wizard
neozip config    # Show current configuration
neozip upgrade <archive> [output] [--wait]  # Upgrade pending Zipstamp timestamp to confirmed

Examples:

# Compress directory recursively
neozip -r archive.nzip ./project/

# Compress with exclusions
neozip -x "*.log" -x "*.tmp" archive.nzip ./src/

# Compress from stdin
find . -name "*.txt" | neozip -@ archive.nzip

# Update existing archive
neozip -u archive.nzip ./src/

# Move files into archive
neozip -m archive.nzip ./temp/

neounzip - Extract Archives

Extract files from ZIP archives.

Basic Syntax:

neounzip [options] <archive> [output]

Common Options:

• -d, --exdir <dir> - Extract to specific directory
• -o, --overwrite - Overwrite files without prompting
• -t, --test - Test archive integrity
• -l, --list - List contents without extracting
• -P, --password <pwd> - Password for encrypted archives (AES-256 and PKZIP auto-detected)
• -x, --exclude <pattern> - Exclude files from extraction
• -i, --include <pattern> - Include only matching files
• -j, --junk-paths - Extract files without directory structure
• -v, --verbose - Enable verbose output
• -q, --quiet - Suppress output

Examples:

# Extract to current directory
neounzip archive.nzip

# Extract to specific directory
neounzip archive.nzip tests/extracted/

# Test archive integrity
neounzip -t archive.nzip

# Extract with exclusions
neounzip -x "*.log" archive.nzip tests/extracted/

# Extract encrypted archive
neounzip --password "mypassword" secure.nzip tests/extracted/

neolist - List Archive Contents

List and inspect ZIP archive contents.

Basic Syntax:

neolist [options] <archive>

Common Options:

• -v, --verbose - Detailed listing
• -s, --short - Short format
• -j, --json - Output as JSON
• -u, --unix - Unix-style listing
• -b, --basic - Basic listing
• -1 - Filenames only
• -2 - Filenames with header/totals

Examples:

# Basic listing
neolist archive.nzip

# Verbose listing
neolist -v archive.nzip

# JSON output
neolist -j archive.nzip

# Filenames only
neolist -1 archive.nzip

Configuration

Wallet Setup (for Blockchain Features)

To use blockchain features, you need to configure a wallet:

# Interactive setup wizard
neozip init

This will guide you through:

1. Creating or importing a wallet
2. Selecting a blockchain network
3. Saving configuration to ~/.neozip/wallet.json

Environment Variables

You can also configure via environment variables:

export NEOZIP_WALLET_PASSKEY="your-wallet-key"
export NEOZIP_NETWORK="base-sepolia"  # or base-mainnet, arbitrum-sepolia, etc.
export ZIPSTAMP_SERVER_URL="https://zipstamp-dev.neozip.io"  # Zipstamp server (optional)
export NEOZIP_TIMESTAMP_EMAIL="[email protected]"  # Email for Zipstamp (some servers require verified email)

Configuration File

Configuration is stored in ~/.neozip/wallet.json:

{
  "walletKey": "0x...",
  "network": "base-sepolia",
  "rpcUrl": "https://..."
}

Advanced Examples

Common Workflows

# Create archive
neozip project.nzip src/ docs/ README.md

# List contents
neolist project.nzip

# Extract files
neounzip project.nzip tests/extracted/

# Test integrity
neounzip -t project.nzip

Compression Options

# Maximum compression
neozip -9 archive.nzip large-folder/

# Fast compression
neozip -1 archive.nzip large-folder/

# Store only (no compression)
neozip -0 archive.nzip already-compressed-files/

File Selection

# Include only JavaScript files
neozip -i "*.js" code.nzip ./src/

# Exclude log files
neozip -x "*.log" -x "*.tmp" clean.nzip ./project/

# Recursive with exclusions
neozip -r -x "node_modules" -x "*.log" project.nzip ./

Encryption

# Create AES-256 encrypted archive (default)
neozip -e -P "secure-password" secret.nzip sensitive-files/

# Create legacy PKZIP encrypted archive
neozip --pkzip -P "secure-password" legacy.nzip sensitive-files/

# Extract encrypted archive (auto-detects encryption method)
neounzip -P "secure-password" secret.nzip decrypted/

Blockchain Features

# Tokenize archive
neozip -b tokenized.nzip important-file.txt

# Tokenize with OpenTimestamp
neozip -ots timestamped.nzip document.pdf

# Extract and verify
neounzip tokenized.nzip verified/

Advanced Operations

# Update existing archive
neozip -u archive.nzip ./updated-files/

# Move files into archive
neozip -m archive.nzip ./temp-files/

# Delete files from archive
neozip -d archive.nzip old-file.txt

# Preserve file permissions
neozip -X archive.nzip ./files/

# Handle symbolic links
neozip -y archive.nzip ./symlinks/

Requirements

• Node.js: 16.0.0 or higher
• Platform: macOS, Linux, or Windows
• Disk Space: ~1MB for installation, additional space for archives

Documentation

The following documentation is included with this package:

• README.md - This file, containing installation, usage, and examples
• WHY_NEOZIP.md - Introduction to NeoZip and its blockchain integration
• CHANGELOG.md - Version history and release notes
• DOCUMENTATION.md - Complete documentation index and reference

Troubleshooting

Installation Issues

Command not found after installation:

# Verify npm global bin path is in your PATH
npm config get prefix

# Add to PATH if needed (example for macOS/Linux)
export PATH="$(npm config get prefix)/bin:$PATH"

Permission errors:

# Use sudo (not recommended) or fix npm permissions
sudo npm install -g neozip-cli@beta

# Better: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Runtime Issues

Archive integrity errors:

# Test archive integrity
neounzip -t archive.nzip

# Recreate archive if corrupted
neozip new-archive.nzip original-files/

Blockchain errors:

# Check wallet configuration
neozip config

# Reconfigure wallet
neozip init

Encryption errors:

# Verify password is correct
neounzip -P "your-password" archive.nzip

# Use legacy PKZIP if AES-256 is not supported by target tool
neozip --pkzip -P "password" archive.nzip files/

Contributing

We welcome feedback and contributions:

1. Report Issues: Use GitHub Issues or email [email protected]
2. Suggest Features: Share your ideas and use cases
3. Test and Provide Feedback: Help us improve by testing and reporting your experience

Important: Please test thoroughly and report issues. See CHANGELOG.md for version history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• GitHub Issues: Report bugs or request features (public issue tracker)
• Email Support: [email protected]
• Documentation: See DOCUMENTATION.md for detailed guides

Acknowledgments

• Built with [NeoZipKit] - coming soon
• Compatible with InfoZip utilities
• Follows ZIP format specification (APPNOTE.TXT)

Version: 0.90.0 Status: Release (see CHANGELOG.md for latest changes) Last Updated: March 18, 2026