packup-cli

Pack folders into portable, integrity-verified strings. Supports encryption for secure sharing.

How it works

Pack Flow (default: encrypted)

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Folder    │────▶│  ZIP Buffer │────▶│  AES-256   │────▶│   Base64    │────▶│  PACKUP:2:  │
│  ./src/*    │     │  (in memory)│     │  encrypt    │     │   encode    │     │  hash:data  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                        ┌──────┴──────┐
                                        │  Password   │
                                        │  + PBKDF2   │
                                        └─────────────┘

Pack Flow (with -u: unencrypted)

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Folder    │────▶│  ZIP Buffer │────▶│   Base64    │────▶│  PACKUP:1:  │
│  ./src/*    │     │  (in memory)│     │   encode    │     │  hash:data  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Unpack Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  PACKUP:1:  │────▶│   Verify    │────▶│   Base64    │────▶│   Extract   │
│  hash:data  │     │  SHA-256    │     │   decode    │     │   to disk   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Installation

npm install -g packup-cli   # global install (recommended)
npm install packup-cli      # local install

CLI Usage

Pack a folder

# Pack to clipboard (encrypted, code only)
packup pack ./my-folder

# Pack to file
packup pack ./my-folder -o packed.txt

# Pack without encryption
packup pack ./my-folder -u

# Pack with binary media (images, video, audio, pdf, fonts)
packup pack ./my-folder -m

Unpack

# Unpack from clipboard
packup unpack ./destination

# Unpack from file
packup unpack ./destination -i packed.txt

If the packed string is encrypted, you'll be prompted for the password.

Info

# Show info from clipboard
packup info

# Show info from file
packup info -i packed.txt

Encryption

Encryption is enabled by default. Use -u to disable:

packup pack ./folder              # encrypted (default)
packup pack ./folder -u           # unencrypted

Features:

• AES-256-CBC encryption (default)
• PBKDF2 key derivation (100,000 iterations)
• SHA-256 integrity verification
• Cross-compatible with the bash version

Media Handling

By default, packup excludes binary media for clean code sharing:

packup pack ./project        # code only (default)
packup pack ./project -m     # include media files

Default (code only): excludes .jpg, .png, .gif, .mp4, .mp3, .pdf, .ttf, .woff, etc.

Always included: .svg (text-based), .css, .js, .html, .json, .md, etc.

AI Agent / Automation

For non-interactive use, set the PACKUP_PASSWORD environment variable:

export PACKUP_PASSWORD="mysecretpassword"
packup pack ./folder -o packed.txt
packup unpack ./dest -i packed.txt

API Usage

import { pack, unpack, info, isEncrypted } from 'packup-cli';

// Pack a folder
const packedString = await pack('./my-folder');

// Pack with encryption
const encrypted = await pack('./my-folder', { password: 'secret' });

// Check if encrypted
if (isEncrypted(packedString)) {
  console.log('This package is encrypted');
}

// Unpack
await unpack(packedString, './destination');
await unpack(encrypted, './destination', { password: 'secret' });

// Get info
const metadata = await info(packedString);
console.log(metadata.files);

Format

Packup strings follow this format:

PACKUP:<version>:<sha256-hash>:<base64-data>

• Version 1: Unencrypted
• Version 2: Encrypted (AES-256-CBC)

License

MIT