CLI Reference

Complete reference for all zipbundler command-line options.

zipapp-Compatible Interface

Zipbundler supports a python -m zipapp compatible command-line interface that matches the standard library’s zipapp module exactly:

zipbundler SOURCE [OPTIONS]

Positional Arguments:

Options:

Examples:

# Basic usage (no shebang, uses __main__.py if present)
zipbundler src/myapp -o app.pyz

# With shebang and entry point
zipbundler src/myapp -o app.pyz -p "/usr/bin/env python3" -m "myapp:main"

# With compression (shorthand)
zipbundler src/myapp -o app.pyz -m "myapp:main" -c

# With compression (long form)
zipbundler src/myapp -o app.pyz -m "myapp:main" --compress

# Display info from existing archive
zipbundler app.pyz --info

# Display info from archive using directory auto-derivation
zipbundler myapp --info

# Modify existing archive (requires -o)
zipbundler app.pyz -o app_new.pyz -p "/usr/bin/env python3"

# Build with zipapp compatibility mode
zipbundler src/myapp -o app.pyz --compat

Compatibility Notes:

Special Modes

--info Command

Display interpreter and metadata information from an existing archive.

zipbundler --info ARCHIVE
zipbundler --info DIRECTORY

The --info command shows:

Directory Auto-Derivation: If SOURCE is a directory, zipbundler automatically looks for {dirname}/{dirname}.pyz in that directory. This is convenient for the common pattern where your source and built archive share the same parent directory name.

Examples:

# Display info from a specific archive file
zipbundler --info dist/myapp.pyz

# Display info using directory auto-derivation
# Looks for: myapp/myapp.pyz
zipbundler --info myapp

--compat Flag

Enable compatibility mode for Python zipapp. This flag is reserved for future strict Python zipapp compatibility and ensures your builds will remain compatible with stdlib zipapp behavior in future versions.

Current Status:

Recommendation: Use --compat if you require compatibility with Python’s stdlib zipapp module. This ensures your builds won’t break if we add strict compatibility mode features in the future.

Example:

# Build with compatibility mode enabled
zipbundler src/myapp -o app.pyz --compat

# Works with all other options
zipbundler src/myapp -o app.pyz -p "/usr/bin/env python3" -m "myapp:main" --compat

Commands

zipbundler build

Build a zip file from the current directory or configuration file.

zipbundler build [OPTIONS]

Options:

Include Path Format:

Destinations in the zip are relative paths. For example:

Examples:

# Build using default config
zipbundler build

# Build with custom config
zipbundler build --config custom.jsonc

# Append additional directories to config packages
zipbundler build --add-include extra/lib

# Append multiple items with custom destinations
zipbundler build \
  --add-include config.json:etc/config.json \
  --add-include README.md:docs/README.md

# Override includes (replace config)
zipbundler build --include "src/pkg1/**/*.py" "src/pkg2/**/*.py"

# Preview without building
zipbundler build --dry-run

# Build with compression
zipbundler build --compress --compression-level 9

# Force rebuild
zipbundler build --force

# Ignore .gitignore patterns (include all files)
zipbundler build --no-gitignore

# Respect .gitignore (default behavior)
zipbundler build --gitignore

# Append new packages to an existing zipapp
zipbundler build --input dist/app.pyz --force

# Update packages in an existing zipapp using a directory path
zipbundler build --input dist --force

# Append additional files to existing zipapp
zipbundler build --input existing.pyz --add-include new_module.py --force

zipbundler init

Create a default configuration file.

zipbundler init [OPTIONS]

Options:

Examples:

# Create default config
zipbundler init

# Create with custom name
zipbundler init --output my-config.jsonc

# Overwrite existing
zipbundler init --force

zipbundler list

List packages and files that would be included in the bundle.

zipbundler list [OPTIONS]

Options:

Examples:

# List all files
zipbundler list

# Show as tree
zipbundler list --tree

# Just count
zipbundler list --count

zipbundler validate

Validate a configuration file.

zipbundler validate [OPTIONS]

Options:

Examples:

# Validate default config
zipbundler validate

# Validate custom config
zipbundler validate --config custom.jsonc

# Strict validation
zipbundler validate --strict

zipbundler watch

Watch for file changes and rebuild automatically.

zipbundler watch [OPTIONS]

Options:

Examples:

# Watch with default settings
zipbundler watch

# Watch with custom interval
zipbundler watch --interval 2.0

Global Options

These options apply to all commands:

Exit Codes

Examples

Basic Workflow

# Initialize config
zipbundler init

# Validate config
zipbundler validate

# Preview what will be bundled
zipbundler list

# Build the zip
zipbundler build

# Watch for changes
zipbundler watch

Advanced Usage

# Build with multiple package sources
zipbundler build \
  --packages "src/pkg1,src/pkg2,installed_pkg" \
  --exclude "**/tests/**,**/docs/**" \
  --output dist/combined.zip

# Build executable zip
zipbundler build \
  --entry-point "myapp.__main__:main" \
  --output dist/myapp.zip

# Dry run to check configuration
zipbundler build --dry-run --verbose

# Build with deterministic timestamps for reproducible builds
zipbundler build --disable-build-timestamp

# Build with deterministic timestamps via environment variable
DISABLE_BUILD_TIMESTAMP=true zipbundler build

# Update existing zipapp with new packages
zipbundler build --input dist/app.pyz --force

# Incremental builds: append new modules to existing zipapp
zipbundler build --input existing.pyz --add-include src/new_module.py --force

Incremental Builds with --input

The --input flag allows you to start from an existing zipapp and update it with new or modified packages:

# Initial build
zipbundler build -o dist/app.pyz

# Add new packages to the existing zipapp
zipbundler build --input dist/app.pyz --force

# The new build will:
# - Preserve all files from the input archive that aren't being updated
# - Update any packages specified in the current build
# - Replace PKG-INFO and __main__.py if new metadata or entry point is provided
# - Preserve other metadata files (if any)

Use Cases: