NeoZip CLI

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

Release Notice

Current version: v1.0.0 — first stable (non-beta) release. See CHANGELOG.md for the full history.

This release includes APPNOTE §6 Merkle v1, origin-aware Token Service networks (production = Base Mainnet; hosted testnet = Base Sepolia), Stripe membership for billed Token Services (neozip connect membership), AI agent JSON I/O and bundled Skills, and --legacy InfoZip compatibility.

• API Stability: Command-line interface is stable for 1.x. Breaking changes will bump the major version.
• Requirements: Node.js 22.15 or higher (native zstd).
• Feedback: Bug reports via GitHub Issues or [email protected]

Overview

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

• Standard ZIP Compatibility: ~99% compatible with InfoZip utilities (--legacy for stock unzip)
• Blockchain Integration: Tokenize archives and verify integrity on-chain
• NeoZip Token Service: Email-verified timestamps, wallet-linked identity, and testnet gas grants
• AI Agent Ready: Machine-readable JSON I/O, schema introspection, dry-run, and bundled Skills
• 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 (-b): Create on-chain tokens for archives (signs locally with the Data Wallet)
• OpenTimestamp (-ots): Bitcoin blockchain timestamping
• Token Service (-ts): Ethereum timestamping via the NeoZip Token Service (requires a verified account)
• Integrity Verification: Verify archive integrity on-chain during extract (neounzip --pre-verify)
• Wallet funding: Request testnet gas grants via neozip connect fund
• 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 22.15.0 or higher
• pnpm 10+ (required for development from source)
• npm (optional — for global install of the published package only)

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 Token Service timestamp (Ethereum)
neozip -ts timestamped.nzip file.txt

# Upgrade pending Token Service timestamp to confirmed
neozip upgrade timestamped.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 Token Service timestamp (Ethereum; requires neozip connect)
• -T, --test-integrity - Test archive after creation
• -v, --verbose - Enable verbose output
• -q, --quiet - Suppress output

Configuration Commands:

neozip connect   # Token Service account + wallet setup (alias: neozip init)
neozip config    # Connection dashboard (status, prefs, migrate)
neozip upgrade <archive> [output] [--wait]  # Upgrade pending Token Service 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

Account and wallet setup

All wallet identity and Token Service credentials live in the shared connection store (~/.neozip/connection/). Use the same profile as NeoZip Desktop and the neozip-mcp server.

neozip connect          # Interactive setup (alias: neozip init)
neozip connect status   # Show connection phase, credentials, membership
neozip connect settings # Default network, RPC overrides, gas prefs
neozip connect membership status|checkout|portal  # $10/year Stripe (billed hosts)
neozip connect migrate  # Import legacy wallet.json / MCP profiles
neozip config           # Connection dashboard (status, prefs, migrate)

On-chain preferences (defaultNetwork, custom RPC URLs, gas) are stored in each connection's public.json. The default network follows the Token Service origin (production → Base Mainnet; hosted testnet → Base Sepolia).

| Token Service | Default chain | Allowed | Membership | |---------------|---------------|---------|------------| | Hosted testnet | Base Sepolia | Sepolia only | Free | | Production | Base Mainnet | Mainnet only | $10/year Stripe |

Membership — production Token Service requires an active annual membership to stamp (-ts) and prepare-mint. Hosted testnet stays free. Skipping checkout during neozip connect does not block wallet setup; create paths return HTTP 402 until you pay.

neozip connect membership status --json
neozip connect membership checkout --json    # Stripe Checkout URL
neozip connect membership portal --json

NeoZip Token Service

The Token Service provides email-verified identity, Ethereum timestamps (-ts), and optional testnet gas grants. Configuration is read only from the connection store — not from env vars or CLI flags.

Setup (interactive or scripted):

neozip connect register --email [email protected] --json
neozip connect verify --email [email protected] --code 123456 --json
neozip connect wallet create --ack-backup --json
neozip connect finish --json

Token refresh — access tokens expire. Renewal prefers a silent wallet-signature login (no email round-trip); falls back to email OTP on older deployments:

neozip connect refresh --json                              # silent wallet login (preferred)
neozip connect refresh --email [email protected] --json      # send OTP code
neozip connect refresh --email [email protected] --code 123456 --json

-ts auto-renews an expired token before failing, so timestamping usually needs no manual step. -b tokenization and mint sign on-chain with the local wallet key and do not require a current access token.

Wallet funding — on-chain operations need native gas. The Token Service can send a small fixed testnet grant to your primary linked wallet (recipient is server-authoritative). Mainnet (8453) funding is not available.

neozip connect fund policy --json    # grant size + cooldown (no auth)
neozip connect fund status --json    # eligibility and recent grants
neozip connect fund --json           # request a grant (default action)
neozip connect fund --network base-sepolia --json

Optional overrides:

export NEOZIP_CONNECTION_DIR="/path/to/connection"  # Store path override
export NEOZIP_UNLOCK_PASSPHRASE="..."               # Decrypt secrets.enc non-interactively
export NEOZIP_NETWORK="base-sepolia"                # Override default network for this session

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 (on-chain mint; needs gas — run neozip connect fund if low)
neozip -b tokenized.nzip important-file.txt

# Token Service timestamp (needs verified account + current access token)
neozip -ts timestamped.nzip document.pdf

# OpenTimestamp (Bitcoin)
neozip -ots timestamped.nzip document.pdf

# Extract and verify on-chain integrity
neounzip --pre-verify 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/

For AI agents

NeoZip is designed for autonomous AI/LLM agents. Every command exposes a stable, machine-readable surface alongside its human interface. Agents can integrate via three paths:

| Path | When to use | |------|-------------| | CLI + JSON | Direct shell invocation from any agent runtime | | Bundled Skills | Cursor, Claude Code, or other skill-aware hosts — load from skills/ | | neozip-mcp | MCP-native agents — same ~/.neozip/connection/ store, tool-based API |

Start with AGENTS.md for engagement rules, then load the relevant skill for each task.

Agent workflow

1. Introspect — neozip schema <neozip|neounzip|neolist|connect> returns accepted fields, types, defaults, and exit codes.
2. Preview — add --dry-run to neozip/neounzip to resolve the full plan as JSON without writing.
3. Execute — run with --format json; parse stdout only (stderr is hints).
4. Recover — on failure, check error.exitCode and run error.nextCommand when present.

neozip schema neozip
neozip --format json --dry-run \
  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
  --json '{"archive":"out.zip","files":["src/","README.md"]}'
neozip --format json \
  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
  --json '{"archive":"out.zip","files":["src/","README.md"]}'

Install Agent Skills

Six bundled skills ship inside the npm package. Install them into Claude Code or Cursor after npm install -g neozip-cli:

| Skill | Covers | |-------|--------| | neozip-shared | JSON output, --params/--json, schema, dry-run, exit codes | | neozip-create | Archive creation: compression, encryption, blockchain flags | | neozip-extract | Extract, test, verify; zip-slip protection; --pre-verify | | neozip-list | List archive contents as JSON | | neozip-connect | Token Service setup, refresh, funding | | neozip-legacy | InfoZip/PKZIP-compatible archives (--legacy) |

# Symlink bundled skills into ~/.claude/skills and ~/.cursor/skills
neozip skills install

# Claude Code only
neozip skills install --target claude

# Show where skills live in your install
neozip skills path
neozip skills list

# ZIP files for Claude Cowork / claude.ai upload (Customize > Skills)
neozip skills pack --output-dir ./neozip-skills-zips

Alternative (skills registry):

npx skills add https://github.com/NeoWareInc/neozip-cli
npx skills add https://github.com/NeoWareInc/neozip-cli/tree/main/skills/neozip-create

JSON I/O conventions

• Output: --format json writes a single object to stdout:
  • Success: { "ok": true, ... }
  • Failure: { "ok": false, "error": { "code", "exitCode", "message", "nextCommand"? } }
• Input: --params '<JSON>' (control options) and --json '<JSON>' (payload: archive + files/targets). Either accepts - to read from stdin. Explicit CLI flags override JSON input.
• Exit codes: InfoZip-compatible; echoed in error.exitCode. Branch on codes, not message text.

Advanced features for agents

| Feature | Agent params / flags | Prerequisites | |---------|---------------------|---------------| | AES-256 encryption | "encrypt": true, "password": "…" | None | | PKZIP encryption | "encryptionMethod": "pkzip" | None | | Zstd compression (default) | "compression": "zstd", "level": 0–9 | Node.js ≥ 22.15 (native zlib streaming) | | InfoZip compatibility | "legacy": true | Disables blockchain extensions | | On-chain tokenization | "blockchain": true | neozip connect + gas (connect fund) | | Token Service timestamp | "blockchainTokenService": true | Verified account + access token | | OpenTimestamp | "blockchainOts": true | None | | Pre-verify on extract | "preVerify": true | Archive must be tokenized | | Network selection | "network": "base-sepolia" | Connection defaultNetwork or override | | --in-memory | ignored | Deprecated no-op; CLI always uses file/chunked streaming (same as Rust NeoZip) |

Blockchain from JSON:

# Tokenize with Token Service timestamp
neozip --format json \
  --params '{"blockchain":true,"blockchainTokenService":true,"network":"base-sepolia"}' \
  --json '{"archive":"tokenized.nzip","files":["contract.pdf"]}'

# Extract with on-chain integrity check
neounzip --format json \
  --params '{"exdir":"out","preVerify":true}' \
  --json '{"archive":"tokenized.nzip"}'

Token Service from an agent — use explicit connect subcommands (not the interactive wizard):

neozip connect status --json
neozip connect refresh --json                    # silent wallet-signature renewal
neozip connect fund status --json                # check gas eligibility
neozip connect fund --json                       # request testnet gas

On config errors, archive commands return error.nextCommand: "neozip connect" so the agent can run setup and retry.

Safety rails

• Archive names and extraction dirs are validated for control characters and dangerous Unicode.
• neounzip refuses zip-slip (entries whose resolved path escapes the target directory).
• --dry-run never touches the filesystem.
• Treat all agent-supplied paths and IDs as potentially adversarial.

InfoZip / PKZIP compatibility

Default compression is zstd, which stock InfoZip unzip cannot read. For consumers that need standard ZIP, pass --legacy (forces deflate/store + PKZIP encryption, disables zstd and all NeoZip extensions). Combining --legacy with blockchain features is a hard error (exit 10). See neozip-legacy.

neozip --format json --params '{"legacy":true,"level":9}' \
  --json '{"archive":"compat.zip","files":["src/"]}'

Requirements

• Node.js: 22.15.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
• AGENTS.md - AI agent engagement rules (JSON I/O, schema, dry-run, exit codes)
• skills/ - Bundled agent Skills for create, extract, list, connect, and legacy mode
• 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

# 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 connection status
neozip connect status

# Re-run setup
neozip connect

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

Development setup

Requires pnpm (packageManager: [email protected]):

pnpm install
pnpm build
pnpm test

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: 1.0.0 Status: Stable Last Updated: August 14, 2026