Latest release v0.95.1

NeoZip CLI

Full-featured command-line ZIP tools built for AI agents — with machine-readable JSON I/O, bundled Agent Skills, NeoZip Token Service Data Wallet setup, Zstandard compression, AES-256 encryption, and on-chain provenance for automation and CI/CD workflows.

Install from npmCommand reference

Overview

NeoZip CLI provides three binaries — neozip, neounzip, and neolist — for archive workflows on macOS, Linux, and Windows. v0.95.1 adds first-class AI agent support alongside deep NeoZip Token Service integration. Use extended help on any command with -h2.

  • AI agent ready — machine-readable JSON I/O, schema introspection, dry-run, and bundled Skills
  • NeoZip Token Service integration — Data Wallet setup, silent token refresh, and testnet gas grants
  • Create, extract, and list archives with Zstd (default), Deflate, or Store compression
  • AES-256 encryption (default) with legacy PKZIP support; ~99% InfoZip-compatible with --legacy
  • On-chain tokenization and Token Service timestamps via the shared ~/.neozip/connection/ store
  • Cross-platform: macOS, Linux, and Windows (Node.js 16+)

Installation

Requires Node.js 16.0.0 or higher. Install globally from npm:

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 — same ~/.neozip/connection/ store, 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–9None
InfoZip compatibility"legacy": trueDisables blockchain extensions
On-chain tokenization"blockchain": trueneozip connect + gas (connect fund)
Token Service timestamp"blockchainTokenService": trueVerified account + access token
Pre-verify on extract"preVerify": trueArchive must be tokenized
Network selection"network": "base-sepolia"Connection defaultNetwork or override

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
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, and optional testnet gas grants via neozip connect fund. 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

# Check gas eligibility and request a testnet grant
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/

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, add Token Service timestamps, 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 if low)
neozip -b tokenized.nzip file.txt

# Token Service timestamp (needs verified account)
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