cli reference

CLI Reference

Quick reference for CyberPatchMaker command-line tools.

Generator Tool

Basic Syntax

patch-gen [options]

Options

Option	Required	Description
`--versions-dir <path>`	Mode 1	Directory containing version folders
`--new-version <version>`	Mode 1	New version number to generate patches for
`--from <version>`	Mode 2	Source version number (with --versions-dir)
`--to <version>`	Mode 2	Target version number (with --versions-dir)
`--from-dir <path>`	Mode 3	Full path to source version directory
`--to-dir <path>`	Mode 3	Full path to target version directory
`--output <path>`	No (default: patches)	Output directory for patches (default: patches)
`--key-file <name>`	No	Specific key file to use (e.g., app_name.exe)
`--compression <type>`	No	Compression: `zstd` (default), `gzip`, `none`
`--level <n>`	No	Compression level: zstd (1-4), gzip (1-3), default: 3
`--verify`	No	Verify patches after creation (default: true)
`--create-exe`	No	Create self-contained CLI executable
`--silent`	No	Embed silent mode into generated executables (requires --create-exe)
`--crp`	No	Create reverse patch for downgrades
`--savescans`	No	Enable scan caching to `.data/` directory
`--scandata <dir>`	No	Custom cache directory (default: `.data`)
`--rescan`	No	Force rescan, ignoring cached data
`--jobs <n>`	No	Number of parallel workers (0 = auto-detect CPU cores, 1 = single-threaded)
`--splitsize <size>`	No	Custom multi-part split size (e.g., '2G', '500M'). Default: 4GB
`--bypasssplitlimit`	No	Bypass 100MB minimum split size confirmation
`--version`	No	Show version information
`--help`	No	Display help information

Exit Codes

Code	Meaning
0	Success
1	Error (all error conditions)

Examples

Mode 1: Batch Mode (generate all patches to new version):

patch-gen --versions-dir ./versions --new-version 1.0.3 --output ./patches

Mode 2: Single Patch (versions in same directory):

patch-gen --from 1.0.1 --to 1.0.3 --versions-dir ./versions --output ./patches

Mode 3: Custom Paths (different drives/locations):

patch-gen --from-dir C:\releases\1.0.0 --to-dir D:\builds\1.0.1 --output ./patches

With Compression:

patch-gen --versions-dir ./versions --new-version 1.0.3 --output ./patches --compression zstd --level 4

With Verification:

patch-gen --versions-dir ./versions --new-version 1.0.3 --output ./patches --verify

With Self-Contained Executables (Silent Mode Embedded):

# Create executables with embedded silent mode (auto-apply)
patch-gen --versions-dir ./versions --new-version 1.0.3 --output ./patches --create-exe --silent --verify

# Result: Users just run 1.0.0-to-1.0.3.exe and patch applies automatically

Applier Tool

Basic Syntax

patch-apply [options]

Options

Option	Required	Description
`--patch <path>`	Yes	Path to patch file
`--current-dir <path>`	Yes	Directory containing current installation
`--key-file <path>`	No	Custom key file path (if renamed or moved)
`--dry-run`	No	Simulate patch without making changes
`--verify`	No	Verify file hashes before and after patching (default: true)
`--backup`	No	Create backup before patching (default: true)
`--ignore1gb`	No	Bypass 1GB patch size limit (use with caution)
`--silent`	No	Silent mode: apply patch automatically without prompts (for automation)
`--version`	No	Show version information
`--help`	No	Show this help message

Backup Flag Details

--backup (default: true)

Strategy: Selective backup of only modified/deleted files (NOT new files)
Location: backup.cyberpatcher folder created inside --current-dir
Structure: Mirror directory hierarchy preserving exact original paths
Preservation: Kept after successful patching for manual rollback capability
Benefits:
- Minimal disk space (e.g., 2.8MB vs 5.2GB = 99.5% reduction)
- Fast backup creation (e.g., 2s vs 45s = 95% faster)
- Intuitive rollback (mirror structure = drag-and-drop restore)
- Transparent about changes (shows exactly what was backed up)

--backup=false

Disables: Backup creation entirely
Risk: Cannot automatically rollback on failure
Use Case: Testing environments, CI/CD pipelines with external backups
WARNING: Not recommended for production systems!

Rollback Procedure (if backup exists):

# Manual rollback from backup.cyberpatcher
Copy-Item C:\MyApp\backup.cyberpatcher\* C:\MyApp -Recurse -Force

# Delete any files that were added (not in backup)
# Then delete backup folder after confirming restoration
Remove-Item C:\MyApp\backup.cyberpatcher -Recurse -Force

See Backup System for complete backup system documentation.

Exit Codes

Code	Meaning
0	Success
1	Error (all error conditions)

Examples

Safe Application (with verification):

patch-apply --patch ./patches/1.0.0-to-1.0.3.patch --current-dir ./myapp --verify

Dry-Run (preview only):

patch-apply --patch ./patches/1.0.0-to-1.0.3.patch --current-dir ./myapp --dry-run

Without Backup (for testing only - NOT recommended!):

patch-apply --patch ./patches/1.0.0-to-1.0.3.patch --current-dir ./myapp --backup=false

Custom Key File (if the key file was renamed):

# If program.exe was renamed to app.exe
patch-apply --patch ./patches/1.0.0-to-1.0.3.patch \
            --current-dir ./myapp \
            --key-file app.exe

# Or with absolute path
patch-apply --patch ./patches/1.0.0-to-1.0.3.patch \
            --current-dir ./myapp \
            --key-file C:\MyApp\renamed_program.exe

Silent Mode (for automation/CI-CD):

# Apply patch automatically without prompts
# Only works with self-contained executables
1.0.0-to-1.0.1.exe --silent

# Silent mode with custom target directory
1.0.0-to-1.0.1.exe --silent --current-dir C:\MyApp

# Silent mode with custom key file
1.0.0-to-1.0.1.exe --silent --current-dir C:\MyApp --key-file renamed.exe

Common Workflows

New Production Release

# 1. Generate all patches to new version
patch-gen --versions-dir ./versions \
          --new-version 1.0.3 \
          --output ./patches \
          --verify

# 2. Test with dry-run
patch-apply --patch ./patches/1.0.2-to-1.0.3.patch \
        --current-dir ./test-app \
        --dry-run

# 3. Apply to production
patch-apply --patch ./patches/1.0.2-to-1.0.3.patch \
        --current-dir C:\Production\MyApp \
        --verify

Downgrade Patches (Rollback to Previous Version)

Generate downgrade patch:

# Generate patch to downgrade from 1.0.3 back to 1.0.2
patch-gen --from 1.0.3 \
          --to 1.0.2 \
          --versions-dir ./versions \
          --output ./patches/downgrade \
          --verify

Apply downgrade patch:

# Test rollback
patch-apply --patch ./patches/downgrade/1.0.3-to-1.0.2.patch \
        --current-dir ./test-app \
        --dry-run

# Apply rollback to production
patch-apply --patch ./patches/downgrade/1.0.3-to-1.0.2.patch \
        --current-dir C:\Production\MyApp \
        --verify

Generate all downgrade paths from current version:

# From 1.0.3 to all previous versions
patch-gen --from 1.0.3 --to 1.0.2 --versions-dir ./versions --output ./patches/downgrade
patch-gen --from 1.0.3 --to 1.0.1 --versions-dir ./versions --output ./patches/downgrade
patch-gen --from 1.0.3 --to 1.0.0 --versions-dir ./versions --output ./patches/downgrade

Result:

patches/downgrade/
├── 1.0.3-to-1.0.2.patch
├── 1.0.3-to-1.0.1.patch
└── 1.0.3-to-1.0.0.patch

Note: For complete downgrade documentation, see Downgrade Guide

Custom Patch with Maximum Compression

# Generate single patch with highest compression
patch-gen --from 1.0.1 \
          --to 1.0.3 \
          --versions-dir ./versions \
          --output ./patches \
          --compression zstd \
          --level 4 \
          --verify

Quick Testing

# Generate without compression (fastest)
patch-gen --versions-dir ./versions \
          --new-version 1.0.3 \
          --output ./patches \
          --compression none

# Apply without verification (fastest)
patch-apply --patch ./patches/1.0.0-to-1.0.3.patch \
        --current-dir ./test-app

Large Projects with Scan Cache

# First generation: Enable scan caching (scans and saves to cache)
patch-gen --versions-dir ./versions \
          --new-version 1.0.3 \
          --output ./patches \
          --savescans

# Subsequent generations: Load from cache (instant, no rescanning)
patch-gen --versions-dir ./versions \
          --new-version 1.0.4 \
          --output ./patches \
          --savescans

# Custom cache location
patch-gen --versions-dir ./versions \
          --new-version 1.0.3 \
          --output ./patches \
          --savescans \
          --scandata ./shared-cache

# Force rescan (update cache with latest file data)
patch-gen --versions-dir ./versions \
          --new-version 1.0.3 \
          --output ./patches \
          --savescans \
          --rescan

Benefits:

Small projects: Minimal improvement (5-10ms saved)
Large projects: Massive improvement (15+ minute scan → <1 second load)
Example: War Thunder (34,650 files) - 15 min scan → instant cache load
Cache validates key file hash to prevent using stale data
Works with both --versions-dir and custom paths (--from-dir/--to-dir)
Cache files stored as JSON with complete file metadata

Environment Variables

Currently, no environment variables are used. All configuration is via command-line flags.

Configuration Files

Configuration can be set via command-line flags. A configuration file is also supported (see development-setup.md for details).

Output Format

Generator Output

Scanning versions directory: ./versions
Found versions: 1.0.0, 1.0.1, 1.0.2
New version: 1.0.3

Generating patch 1.0.0 -> 1.0.3...
  Loading manifests...
  Comparing versions...
  Processing modified files (full replacement)...
  Compressing (zstd level 3)...
  Patch saved to: patches/1.0.0-to-1.0.3.patch (2.1 MB)

Generating patch 1.0.1 -> 1.0.3...
  ...
  ✓ Success: patches/1.0.1-to-1.0.3.patch (1.8 MB)

Generating patch 1.0.2 -> 1.0.3...
  ...
  ✓ Success: patches/1.0.2-to-1.0.3.patch (1.2 MB)

All patches generated successfully!
Total: 3 patches, 5.1 MB

Applier Output

Loading patch: patches/1.0.0-to-1.0.3.patch

=== Patch Information ===
From Version: 1.0.0
To Version:   1.0.3
Key File:     program.exe
Created:      2025-10-04 10:30:00
Patch Size:   2.1 MB
Compression:  zstd

Operations:
  5 files to add
  12 files to modify
  3 files to delete

Applying patch from 1.0.0 to 1.0.3...
Verifying current version...
✓ Pre-patch verification successful

Creating selective backup...
  Backing up: program.exe
  Backing up: data/config.json
  Backing up: libs/oldfeature.dll
  ... (9 more files - only changed/deleted files)
✓ Selective backup created

Applying 20 operations...
  Modified: program.exe
  Modified: data/config.json
  Added: libs/newfeature.dll (NOT backed up - didn't exist before)
  Deleted: libs/oldfeature.dll
  ... (16 more operations)

✓ Post-patch verification successful

Backup preserved in: ./myapp/backup.cyberpatcher

=== Patch Applied Successfully ===
Version updated from 1.0.0 to 1.0.3
Time elapsed: 8.2 seconds (selective backup saved time!)

Platform-Specific Notes

Windows

PowerShell:

.\patch-gen.exe --versions-dir .\versions --new-version 1.0.3 --output .\patches
.\patch-apply.exe --patch .\patches\1.0.0-to-1.0.3.patch --current-dir .\myapp --verify

Command Prompt (cmd):

patch-gen.exe --versions-dir .\versions --new-version 1.0.3 --output .\patches
patch-apply.exe --patch .\patches\1.0.0-to-1.0.3.patch --current-dir .\myapp --verify

Paths: Use backslashes \ or forward slashes / (both work)

Linux/macOS

Bash:

./patch-gen --versions-dir ./versions --new-version 1.0.3 --output ./patches
./patch-apply --patch ./patches/1.0.0-to-1.0.3.patch --current-dir ./myapp --verify

Paths: Use forward slashes /

Permissions: May need to make executables:

chmod +x generator applier

Automation Scripts

PowerShell Script Example

# generate-patches.ps1
param(
    [string]$NewVersion = "1.0.3",
    [string]$VersionsDir = "./versions",
    [string]$OutputDir = "./patches"
)

Write-Host "Generating patches for version $NewVersion..."

& .\patch-gen.exe `
    --versions-dir $VersionsDir `
    --new-version $NewVersion `
    --output $OutputDir `
    --verify

if ($LASTEXITCODE -eq 0) {
    Write-Host "Success! Patches generated in $OutputDir"
} else {
    Write-Error "Patch generation failed with exit code $LASTEXITCODE"
    exit $LASTEXITCODE
}

Usage:

.\generate-patches.ps1 -NewVersion 1.0.4

Bash Script Example

#!/bin/bash
# generate-patches.sh

NEW_VERSION=${1:-"1.0.3"}
VERSIONS_DIR="./versions"
OUTPUT_DIR="./patches"

echo "Generating patches for version $NEW_VERSION..."

./patch-gen \
    --versions-dir "$VERSIONS_DIR" \
    --new-version "$NEW_VERSION" \
    --output "$OUTPUT_DIR" \
    --verify

if [ $? -eq 0 ]; then
    echo "Success! Patches generated in $OUTPUT_DIR"
else
    echo "Patch generation failed with exit code $?"
    exit $?
fi

Usage:

chmod +x generate-patches.sh
./generate-patches.sh 1.0.4

Uh oh!

cli reference

CLI Reference

Generator Tool

Basic Syntax

Options

Exit Codes

Examples

Applier Tool

Basic Syntax

Options

Backup Flag Details

Exit Codes

Examples

Common Workflows

New Production Release

Downgrade Patches (Rollback to Previous Version)

Custom Patch with Maximum Compression

Quick Testing

Large Projects with Scan Cache

Environment Variables

Configuration Files

Output Format

Generator Output

Applier Output

Platform-Specific Notes

Windows

Linux/macOS

Automation Scripts

PowerShell Script Example

Bash Script Example

Related Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally