packmime

A command-line tool that creates MIME multipart archives from files and directories.

Context

I created this 90s-era command in 2024 because this encoding is great for talking to LLMs, and the old commands are pretty clumsy for what I want.

I use it with llpipe and unpackmime or as part of dv

This code was written by Claude 3.5. See manual-bootstrap.

Features

• Recursively includes files from directories
• Preserves file metadata (executable bits, modification times)
• Automatically handles binary files with base64 encoding
• Supports form fields in addition to file attachments
• Respects .gitignore patterns and ignores .git directory
• Provides a summary of included content

Installation

npm install -g packmime

Usage

packmime [options] [files...] [field=value...]

Arguments

• files...: Files or directories to include in the archive
• field=value...: Form fields to include (must start with a letter)

Options

• --use-ignore-file=<path>: Use specified ignore file instead of .gitignore
• --help: Show help message

Examples

Create an archive with some files:

packmime file1.txt directory/ > archive.mime

Include form fields:

packmime name="John Doe" [email protected] file1.txt > archive.mime

Use a custom ignore file:

packmime --use-ignore-file=.customignore directory/ > archive.mime

Talk to AI:

packmime prompt='Please review this code for errors.' . | llpipe

Output Format

The tool creates a standard MIME multipart archive with these characteristics:

• Form fields appear first, followed by file attachments
• Binary files are automatically base64 encoded
• File permissions and modification times are preserved using de facto standard headers
• Uses CRLF line endings as per MIME specification
• Automatically generates a unique boundary that doesn't conflict with file contents
• Relative paths are preserved in filename attributes

The tool writes the MIME content to stdout and a summary to stderr.

Metadata Headers

For each file attachment, the following headers are included:

• Content-Disposition: Contains the relative pathname
• Content-Type: Set to application/octet-stream
• Content-Transfer-Encoding: Set to base64 for binary files
• Content-Mode: Added if the file is executable
• Content-Modified: Contains the file's last modification time

Error Handling

• Invalid arguments show usage information
• File access errors are reported with appropriate messages
• Non-UTF8 content is automatically detected and base64 encoded

Limitations

• Files are loaded entirely into memory
• Form field names must start with a letter
• Arguably we should base64 encode non-ASCII UTF8 content

License

MIT