mcpack

Fast, resumable CLI installer for CurseForge manifest-based Minecraft modpacks.

mcpack installs modpacks from manifest.json + overrides/ without requiring CurseForge/Overwolf launchers.

Why mcpack

• Launcher-agnostic workflow for Linux, macOS, and Windows
• Automatic instance structure creation (mods, config, scripts, etc.)
• Parallel downloads with retry and timeout controls
• Resume support via mods/.mod-download-state.json
• Dry-run mode for safe preview before real install
• Clean Architecture codebase for maintainability and extension

Requirements

• Node.js 18.17+
• Network access to curseforge.com and forgecdn.net

Installation

npm install -g mcpack-cli

Local development setup:

npm install
npm run build
node dist/cli.js --help

Quick Start

mcpack install --source /path/to/modpack --target /path/to/instance

After installation:

1. Install the loader version from your manifest.json (for this pack: neoforge-21.1.219).
2. Point launcher Game Directory to the generated instance directory.
3. Set RAM according to pack recommendations.

Command Reference

| Option | Description | Default | |---|---|---| | -s, --source <dir> | Path containing manifest.json and overrides/ | current directory | | -t, --target <dir> | Target instance directory | <source>/instance | | -c, --concurrency <num> | Parallel downloads | 6 | | -r, --retries <num> | Retries per file | 2 | | --timeout-ms <num> | Timeout per request in milliseconds | 60000 | | --required-only | Download only entries with required=true | off | | --skip-overrides | Skip copying overrides/ | off | | --skip-mods | Skip mod downloads, keep structure+metadata only | off | | --dry-run | Show planned actions without writing files | off | | --force-overwrite | Overwrite files on name collisions | off | | -h, --help | Show help | off |

Practical Examples

# Preview everything without changing disk
mcpack install --source .. --target ../instance --dry-run

# Generate instance skeleton + overrides only
mcpack install --source .. --target ../instance --skip-mods

# More aggressive download profile
mcpack install --source .. --target ../instance --concurrency 10 --retries 4

# Only required files from manifest
mcpack install --source .. --target ../instance --required-only

Output and Exit Codes

• Exit code 0: success
• Exit code 2: completed with failed downloads
• Exit code 1: CLI or validation/runtime error

If some files fail, rerun the same command: mcpack resumes from saved state.

Architecture

The project follows Clean Architecture:

src/
    domain/
        entities/
        ports/
    application/
        use-cases/
    infrastructure/
        download/
        fs/
        logging/
        manifest/
    presentation/
        cli/
    cli.ts

• domain: business contracts and models (no framework/runtime details)
• application: orchestrates use-cases through domain ports
• infrastructure: concrete adapters (Node FS, CurseForge downloader, logger)
• presentation: CLI parsing/help and UX concerns
• cli.ts: composition root (wires adapters into use-case)

Development

npm run typecheck
npm run build
npm run release:check

Publishing

Minimal flow:

npm run release:check
npm version patch
npm publish

Full publishing checklist is available in PUBLISHING.md.

Limitations

• mcpack does not install NeoForge/Fabric/Forge into launcher profiles.
• Availability of mod files depends on CurseForge/CDN accessibility.