coldpack

English | 繁體中文

A Python CLI tool for creating standardized 7z archives for long-term data storage with integrity verification, PAR2 recovery, and cross-platform compatibility.

Overview

coldpack is a command-line tool for creating standardized cold storage archives. It converts various source formats (directories, zip, tar, etc.) into 7z archives with integrated verification and recovery mechanisms designed for long-term data preservation.

Features

Core Functionality

• 7z-only output: Converts various input formats to standardized 7z archives
• Adaptive compression: Automatically selects compression parameters based on file size
• Command-line interface: Simple CLI commands for archive management

Available Commands

• cpack create - Create 7z cold storage archives
• cpack extract - Extract archives with parameter restoration
• cpack verify - Verify archive integrity using multiple methods
• cpack repair - Repair corrupted archives using PAR2 recovery
• cpack info - Display archive metadata
• cpack list - List archive contents with filtering options

Verification and Recovery

• Multiple verification layers: 7z integrity, SHA-256, BLAKE3, and PAR2
• Dual hash algorithms: SHA-256 for compatibility, BLAKE3 for performance
• PAR2 recovery files: 10% redundancy for error correction
• Metadata preservation: Stores compression parameters in metadata.toml

Cross-Platform Support

• Operating systems: Windows, macOS, Linux
• System file handling: Automatically excludes platform-specific files (.DS_Store, Thumbs.db)
• Unicode support: Handles international filenames correctly with automatic compatibility
• Progress tracking: Real-time progress display during operations

For detailed installation and usage instructions, see Installation Guide and CLI Reference.

Quick Start

Installation

# Using pip (recommended)
pip install coldpack

# Using uv
uv add coldpack

Requirements: Python 3.9+ | Windows, macOS, Linux

For detailed installation instructions including development setup, see Installation Guide.

Basic Usage

# Create 7z cold storage archive
cpack create /path/to/documents --output-dir ~/cold-storage

# Extract with automatic parameter recovery
cpack extract ~/cold-storage/documents.7z --output-dir ~/restored

# Verify 4-layer integrity
cpack verify ~/cold-storage/documents.7z

# Advanced file listing with filtering
cpack list ~/cold-storage/documents.7z --filter "*.pdf" --limit 10

Advanced Usage

# Custom compression levels (0-9) with memory limit
cpack create large-dataset/ --level 9 --dict 512m --memory-limit 2g --output-dir ~/archives

# Memory-constrained compression for limited systems
cpack create documents/ --memory-limit 512m --output-dir ~/archives

# Pre-verification before extraction
cpack extract suspicious-archive.7z --verify --output-dir ~/safe-extraction

# Repair corrupted files using PAR2
cpack repair ~/cold-storage/damaged-archive.7z

# Display metadata information
cpack info ~/cold-storage/documents.7z

See Usage Examples for more use cases and workflows.

Technical Specifications

Supported Input Formats

• Directories: Any filesystem directory structure
• Archive Formats: 7z, zip, rar, tar, tar.gz, tar.bz2, tar.xz, tar.zst

Output Structure

archive-name/
├── archive-name.7z              # Main 7z archive
├── archive-name.7z.sha256       # SHA-256 hash
├── archive-name.7z.blake3       # BLAKE3 hash
├── archive-name.7z.par2         # PAR2 recovery files
└── metadata/
    └── metadata.toml            # Complete archive metadata

Verification System

1. 7z Integrity: Native 7z archive structure validation
2. SHA-256: Cryptographic hash verification (legacy compatibility)
3. BLAKE3: Modern high-performance cryptographic hash
4. PAR2 Recovery: Error correction with 10% redundancy

Compression Optimization

For detailed architecture documentation and configuration options, see Architecture Guide.

Development & Contributing

Development Setup

# Clone and setup development environment
git clone https://github.com/rxchi1d/coldpack.git
cd coldpack
uv sync --dev
source .venv/bin/activate

Quality Assurance

# Code formatting and linting
uv run ruff format . && uv run ruff check --fix .

# Type checking and testing
uv run mypy src/ && uv run pytest

Development Standards: Comprehensive test suite, ruff formatting, MyPy type checking, cross-platform CI/CD

See CLAUDE.md for complete development instructions.

License & Support

License: MIT - See LICENSE and LICENSES/MIT.txt for details Third-party Dependencies: This project does not redistribute 7-Zip binaries; runtime dependencies (py7zz, PAR2 tools) are installed by users and governed by their upstream licenses.

Documentation:

• Installation Guide - Setup instructions
• CLI Reference - Command documentation
• Usage Examples - Use cases and workflows
• Architecture Guide - Technical implementation details

Support: GitHub Issues | Discussions