Stable release v1.0.0

NeoZip CLI

First stable SemVer 1.0 command-line ZIP tools — AI agent JSON I/O, bundled Agent Skills, NeoZip Token Service Data Wallet setup (Base Sepolia and Base Mainnet), APPNOTE §6 Merkle v1 provenance, Zstandard compression, and AES-256 encryption for automation and CI/CD.

Install from npmCommand reference

Overview

NeoZip CLI provides three binaries — neozip, neounzip, and neolist — for archive workflows on macOS, Linux, and Windows. v1.0.0 is the first stable release: SemVer 1.x CLI stability, APPNOTE §6 Merkle v1, origin-aware Token Service networks, and Stripe membership for billed services. Use extended help on any command with -h2.

  • First stable SemVer 1.0 release — CLI API stable for 1.x; breaking changes bump major
  • AI agent ready — machine-readable JSON I/O, schema introspection, dry-run, and bundled Skills
  • NeoZip Token Service — Data Wallet setup, silent token refresh, testnet gas grants, Stripe membership for billed services
  • APPNOTE §6 Merkle v1 roots for mint / stamp / verify (powered by neozipkit 1.0.5)
  • Create, extract, and list archives with Zstd (default), Deflate, or Store; AES-256 encryption by default
  • ~99% InfoZip-compatible with --legacy; cross-platform macOS, Linux, and Windows (Node.js 22.15+)

Installation

Requires Node.js 22.15.0 or higher (native Zstd). Install globally from npm — no @beta tag:

Install

npm install -g neozip-cli

# Verify installation
neozip --version
neounzip --version
neolist --version

Quick start

A typical workflow: create an archive, inspect it, then extract or test integrity.

Basic workflow

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

# List contents
neolist archive.nzip

# Extract files
neounzip archive.nzip tests/extracted/

# Test integrity
neounzip -t archive.nzip

AI agent integration

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

PathWhen to use
CLI + JSONDirect shell invocation from any agent runtime
Bundled SkillsCursor, Claude Code, or other skill-aware hosts — load via neozip skills install
NeoZip MCPMCP-native agents (v0.9.0-beta) — same ~/.neozip/connection/ store, dual-era MCP, tool-based API

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.

Agent workflow examples

# Introspect accepted fields and exit codes
neozip schema neozip

# Preview a create operation without writing
neozip --format json --dry-run \
  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
  --json '{"archive":"out.zip","files":["src/","README.md"]}'

# Execute with structured output
neozip --format json \
  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
  --json '{"archive":"out.zip","files":["src/","README.md"]}'

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

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.
  • Precedence: explicit CLI flags override values from --params/--json.
  • Exit codes: InfoZip-compatible; echoed in error.exitCode. Branch on codes, not message text.

Advanced features for agents

FeatureAgent paramsPrerequisites
AES-256 encryption"encrypt": true, "password": "…"None
PKZIP encryption"encryptionMethod": "pkzip"None
Zstd compression (default)"compression": "zstd", "level": 0–9Node.js ≥ 22.15
InfoZip compatibility"legacy": trueDisables blockchain extensions
On-chain tokenization"blockchain": trueneozip connect + gas (connect fund on testnet)
Token Service timestamp"blockchainTokenService": trueVerified account + access token
Pre-verify on extract"preVerify": trueArchive must be tokenized
Network selection"network": "base-sepolia" | "base"Must match active Token Service origin

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.

Bundled Agent Skills

Six bundled skills ship inside the npm package. Install them into Claude Code or Cursor after npm install -g neozip-cli. For MCP-native agents, see the NeoZip MCP product page or setup & docs — it shares the same ~/.neozip/connection/ store.

SkillCovers
neozip-sharedJSON output, --params/--json, schema, dry-run, exit codes
neozip-createArchive creation: compression, encryption, blockchain flags
neozip-extractExtract, test, verify; zip-slip protection; --pre-verify
neozip-listList archive contents as JSON
neozip-connectToken Service setup, refresh, funding, membership
neozip-legacyInfoZip/PKZIP-compatible archives (--legacy)

Install Agent Skills

# 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
neozip skills pack --output-dir ./neozip-skills-zips

NeoZip Token Service & Data Wallet

All wallet identity and Token Service credentials live in the shared connection store at ~/.neozip/connection/ — the same profile used by NeoZip Desktop and NeoZip MCP. Run neozip connect (alias: neozip init) to set up your local Data Wallet and verified Token Service account.

The Token Service provides email-verified identity, Ethereum timestamps (-ts), silent wallet-signature token refresh, optional testnet gas grants via neozip connect fund, and Stripe membership for billed production services via neozip connect membership. Hosted testnet defaults to Base Sepolia; production Token Service defaults to Base Mainnet. On-chain tokenization (-b) signs locally with the Data Wallet and does not require a current access token.

Token Service setup

# Scripted setup (non-interactive, agent-friendly)
neozip connect register --email you@example.com --json
neozip connect verify --email you@example.com --code 123456 --json
neozip connect wallet create --ack-backup --json
neozip connect finish --json

# Silent wallet-signature token renewal (preferred)
neozip connect refresh --json

# Membership for billed Token Services (production)
neozip connect membership status --json
neozip connect membership checkout --json
neozip connect membership portal --json

# Testnet gas grants only (Base Sepolia) — not available on Base Mainnet
neozip connect fund status --json
neozip connect fund --json
neozip connect fund --network base-sepolia --json

# Optional overrides
export NEOZIP_CONNECTION_DIR="/path/to/connection"
export NEOZIP_UNLOCK_PASSPHRASE="..."
export NEOZIP_NETWORK="base-sepolia"

Compression

Zstd is the default method. Use Deflate for maximum compatibility, level -0 to store without compression, or --legacy for archives readable by stock InfoZip unzip.

Compression examples

# Default Zstd compression
neozip output.nzip ./src/

# Maximum compression
neozip -9 output.nzip ./src/

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

# Store only (no compression)
neozip -0 output.nzip ./src/

# InfoZip-compatible archive (stock unzip can read)
neozip --legacy -9 compat.zip ./src/

# Scan for old WASM zstd frames
neolist --detect-legacy-zstd archive.nzip

Encryption

AES-256 is the recommended default. Legacy PKZIP encryption is available for compatibility only. Extraction auto-detects the encryption method.

Encryption examples

# AES-256 encrypted archive (prompts for password)
neozip -e secure.nzip file.txt

# With password on the command line
neozip -e -P "mypassword" secure.nzip file.txt

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

Blockchain

Tokenize archives on supported EVM networks (network follows your connection's Token Service origin), add Token Service timestamps with APPNOTE §6 Merkle v1 digests, and verify integrity on extract. Run neozip connect before using blockchain features (see Token Service & Data Wallet above).

Blockchain examples

# Set up Data Wallet and Token Service account first
neozip connect

# Tokenize archive (on-chain mint; needs gas — run neozip connect fund on testnet)
neozip -b tokenized.nzip file.txt

# Token Service timestamp (needs verified account; production stamps Base Mainnet)
neozip -ts timestamped.nzip file.txt

# Upgrade pending Token Service timestamp to confirmed
neozip upgrade timestamped.nzip [output.nzip] [--wait]

# Extract and verify on-chain integrity
neounzip --pre-verify tokenized.nzip verified/

Full command reference

Flags, subcommands, and examples for neozip, neounzip, neolist, connect, skills, schema, and more.

View command reference

Building apps with NeoZipKit or NeoZip-blockchain? See the Developers hub for SDK installation and library documentation.

DevelopersNeoZip DesktopNeoZip MCP