This tool does the complicated bits for the itzg/minecraft-server and itzg/docker-mc-proxy Docker images.
NOTE The following documentation may not always be up-to-date. Please be sure to use
-hor--helpafter any subcommand to view the current usage.
Usage: mc-image-helper [-hsV] [--debug | --logging=<loggingLevel>] [COMMAND]
--debug Enable debug output. Can also set environment variables DEBUG_HELPER or DEBUG
-h, --help Show this usage and exit
--logging=<loggingLevel>
Set logging to specific level.
Valid values:
-s, --silent Don't output logs even if there's an error
-V, --version
Commands:
archive Archive helpers, checking for path traversal and extracting archives
asciify Converts UTF-8 on stdin to ASCII by escaping Unicode characters
assert Provides assertion operators for verifying container setup
compare-versions Used for shell scripting, exits with success(0) when comparison is satisfied or 1
when not
curseforge-files Download and manage individual mod/plugin files from CurseForge
find Specialized replacement for GNU's find
get Download a file
github
hash Outputs an MD5 hash of the standard input
has-feature Check if a subcommand is available and optionally if it has specific options
(arguments)
ini-path Extracts a field from an INI file
install-curseforge Downloads, installs, and upgrades CurseForge modpacks
install-fabric-loader Provides a few ways to obtain a Fabric loader with simple cleanup of previous loader
instances
install-forge Downloads and installs a requested version of Forge
install-cleanroom Downloads and installs a requested version of Cleanroom
install-modrinth-modpack Supports installation of Modrinth modpacks along with the associated mod loader
install-neoforge Downloads and installs a requested version of NeoForge
install-oci-pack Pulls an OCI artifact and writes its layer blobs to disk in apply order
install-paper Installs selected PaperMC
install-purpur Downloads latest or selected version of Purpur
install-quilt Installs Quilt mod loader
install-vanilla Downloads and installs a requested version of vanilla Minecraft
interpolate Interpolates existing files in one or more directories
java-release Outputs the Java release number, such as 8, 11, 17
manage-users
maven-download Downloads a maven artifact from a Maven repository
modrinth Automates downloading of modrinth resources
mcopy Multi-source file copy operation with with managed cleanup. Supports auto-detected
sourcing from file list, directories, and URLs
network-interfaces Provides simple operations to list network interface names and check existence
patch Patches one or more existing files using JSON path based operations
Supports the file formats:
- JSON
- JSON5
- Yaml
- TOML, but processed output is not pretty
- Properties, but comments are not retained
resolve-minecraft-version Resolves and validate latest, snapshot, and specific versions
set-properties Maps environment variables to a properties file
show-all-subcommand-usage Renders all of the subcommand usage as markdown sections for README
sync Synchronizes the contents of one directory to another.
sync-and-interpolate Synchronizes the contents of one directory to another with conditional variable
interpolation.
test-logging-levels
toml-path Extracts a path from a TOML file using json-path syntax
vanillatweaks Downloads Vanilla Tweaks resource packs, data packs, or crafting tweaks given a share
code or pack file
version-from-modrinth-projects Finds a compatible Minecraft version across given Modrinth projects
yaml-path Extracts a path from a YAML file using json-path syntax
For patch command see below for a description of PatchSet and PatchDefinition JSON schemas.
For install-curseforge and install-modrinth-modpack commands, refer to the exclude/include file schema.
Usage: mc-image-helper archive [-h] [COMMAND]
Archive helpers, checking for path traversal and extracting archives
-h, --help
Commands:
check-path-traversal Checks if an archive contains path traversal attack
extract Extracts an archive, checking for path traversal
Usage: mc-image-helper asciify
Converts UTF-8 on stdin to ASCII by escaping Unicode characters
Usage: mc-image-helper assert [COMMAND]
Provides assertion operators for verifying container setup
Commands:
fileExists
fileNotExists
jsonPathEquals
propertyEquals
Usage: mc-image-helper compare-versions <leftVersion> <comparison> <rightVersion>
Used for shell scripting, exits with success(0) when comparison is satisfied or 1 when not
<leftVersion>
<comparison>
<rightVersion>
Usage: mc-image-helper curseforge-files [-h] [--disable-api-caching] [--api-base-url=<apiBaseUrl>] [--api-key=<apiKey>]
[--api-key-file=PATH] [--default-category=<slugCategory>]
[--game-version=<gameVersion>] [--mod-loader=<modLoaderType>] [-o=DIR]
[[--api-cache-ttl=OPERATION=DURATION]... [--api-cache-default-ttl=DURATION]]
[[--use-http2] [--wiretap]] [REF[,|<nl>REF...]...]
Download and manage individual mod/plugin files from CurseForge
[REF[,|<nl>REF...]...]
Can be
<project ID>|<slug>':'<file ID>,
<project ID>|<slug>'@'<filename matcher>,
<project ID>|<slug>,
project page URL, file page URL,
'@'<filename with ref per line>
If not specified, any previous mod/plugin files are removed.
Embedded comments are allowed
--api-base-url=<apiBaseUrl>
Allows for overriding the CurseForge Eternal API used
Can also be passed via CF_API_BASE_URL
--api-cache-default-ttl=DURATION
Set default/fallback TTL in ISO-8601 duration format.
Default: P2D
--api-cache-ttl=OPERATION=DURATION
Set individual operation TTLs
--api-key=<apiKey> An API key allocated from the Eternal developer console at https://console.curseforge.com/
Can also be passed via CF_API_KEY
--api-key-file=PATH Read the API key from a UTF-8 file (instead of passing it directly).
Can also be passed via CF_API_KEY_FILE
--default-category=<slugCategory>
When providing slugs, a category is required to qualify those
--disable-api-caching
--game-version=<gameVersion>
The Minecraft version
Can also be passed via VERSION
-h, --help
--mod-loader=<modLoaderType>
One of Any, Forge, Cauldron, LiteLoader, Fabric, Quilt, NeoForge
-o, --output-directory=DIR
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper find [-hq] [--delete] [--delete-empty-directories] [--fail-no-matches] [--only-shallowest]
[--output-count-only] [--stop-on-first] [--format=<format>] [--max-depth=N] [--min-depth=N]
[--exclude-name=glob[\s*,\s*glob...]]... [--name=glob[\s*,\s*glob...]]... [-t=<type>[\s*,
\s*<type>...]]... startDir...
Specialized replacement for GNU's find
startDir... One or more starting directories
--delete Deletes the matched entries. When searching for directories, each directory and its
contents will be recursively deleted.
--delete-empty-directories
Deletes a traversed directory if it becomes empty after matching files/directories within
it were deleted
--exclude-name=glob[\s*,\s*glob...]
One or more glob patterns to exclude by looking at name part of the path. If a pattern
matches a directory's name, then its entire subtree is excluded.
--fail-no-matches
--format=<format> Applies a format when printing each matched entry. Supports the following directives
%% a literal %
%h leading directory of the entry
%P path of the entry relative to the starting point
-h, --help
--max-depth=N Unlimited depth if negative
--min-depth=N Minimum match depth where 0 is a starting point
--name=glob[\s*,\s*glob...]
One or more glob patterns to match name part of the path
--only-shallowest
--output-count-only
-q, --quiet
--stop-on-first
-t, --type=<type>[\s*,\s*<type>...]
Valid values: file, directory
Usage: mc-image-helper get [-hz] [--exists] [--log-progress-each] [--output-filename] [--skip-existing]
[--apikey=<apikeyHeader>] [--json-path=<jsonPath>]
[--json-value-when-missing=<jsonValueWhenMissing>] [-o=FILE|DIR]
[--prune-depth=<pruneDepth>] [--retry-count=<retryCount>] [--retry-delay=<retryDelay>]
[--uris-file=<urisFile>] [--accept=<acceptContentTypes>[\s*,\s*<acceptContentTypes>...]]...
[--prune-others=GLOB[\s*,\s*GLOB...]]... [URI[\s*,\s*URI...]...]
Download a file
[URI[\s*,\s*URI...]...]
The URI of the resource to retrieve. When the output is a directory, more than one URI can
be requested.
--accept=<acceptContentTypes>[\s*,\s*<acceptContentTypes>...]
Specifies the accepted content type(s) to use with the request
--apikey=<apikeyHeader>
Sets the x-api-key header to use with the request
--exists Test if the given URIs are retrievable
-h, --help Show this usage and exit
--json-path=<jsonPath>
Extract and output a JsonPath from the response
--json-value-when-missing=<jsonValueWhenMissing>
Defines the value that is output when the requested JSON path does not exist. An empty
value results in a non-zero exit code.
--log-progress-each Output a log as each URI is being retrieved
-o, --output=FILE|DIR Specifies the name of a file or directory to write the downloaded content. If a directory
is provided, the filename will be derived from the content disposition or the URI's path.
If not provided, then content will be output to standard out.
--output-filename Output the resulting filename
--prune-depth=<pruneDepth>
When using prune-others, this specifies how deep to search for files to prune
--prune-others=GLOB[\s*,\s*GLOB...]
When set and using an output directory, files that match the given glob patterns will be
pruned if not part of the download set. For example *.jar
--retry-count=<retryCount>
--retry-delay=<retryDelay>
in seconds
--skip-existing Do not retrieve if the output file already exists
--uris-file=<urisFile>
A file that contains a URL per line
-z, --skip-up-to-date Skips re-downloading a file that is up to date
Usage: mc-image-helper github [--api-base-url=<apiBaseUrl>] [--token=<token>] [COMMAND]
--api-base-url=<apiBaseUrl>
--token=<token> An access token for GitHub to elevate rate limit vs anonymous access
Commands:
download-asset, download-latest-asset From the latest or a given release, downloads the first matching asset, and
outputs the downloaded filename
download-artifact Download an artifact from a successful GitHub Actions workflow
Usage: mc-image-helper has-feature <subcommand> [<arguments>...]
Check if a subcommand is available and optionally if it has specific options (arguments)
<subcommand> The subcommand name to check for availability
[<arguments>...] Optional option names to check within the subcommand (e.g., 'help' for --help or -h)
Usage: mc-image-helper hash
Outputs an MD5 hash of the standard input
Usage: mc-image-helper ini-path FILE REF
Extracts a field from an INI file
FILE An INI file to query
REF section/option, section/option[index], /option, /option[index]
Usage: mc-image-helper install-cleanroom [-h] [--force-reinstall] [--output-directory=DIR] [--results-file=FILE]
[[--installer-version=<installerVersion>] |
[--loader-version=<loaderVersion>]] [[--cleanroom-maven-url=URL] |
--from-local-file=FILE | --from-url=URL] [[--use-http2] [--wiretap]]
Downloads and installs a requested version of Cleanroom
--cleanroom-maven-url=URL
URL for Cleanroom Maven repo.
Can also be set via env var CLEANROOM_MAVEN_URL
Default is https://maven.cleanroommc.com/
--force-reinstall
--from-local-file=FILE
Use a local installer, first entry before remote.
--from-url=URL Use a remote installer.
-h, --help
--installer-version=<installerVersion>
A specific Cleanroom installer version or to auto-resolve the version provide 'latest'.
Ignored if valid a local/remote (included legacy) is provided. Default value is latest
--loader-version=<loaderVersion>
A specific Cleanroom Loader version or to auto-resolve by installer.
Ignored if only a valid local/remote legacy installer is provided. Default value is latest
--output-directory=DIR
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-curseforge [-h] [--disable-api-caching] [--force-reinstall-modloader]
[--force-synchronize] [--overrides-skip-existing]
[--api-base-url=<apiBaseUrl>] [--api-key=<apiKey>] [--api-key-file=PATH]
[--downloads-repo=DIR] [--file-download-retries=COUNT]
[--file-download-retry-min-delay=DURATION] [--file-id=<fileId>]
[--filename-matcher=STR]
[--max-concurrent-downloads=<maxConcurrentDownloads>]
[--missing-mods-filename=<missingModsFilename>]
[--mod-loader-version=VERSION] [--modpack-manifest=PATH]
[--modpack-page-url=URL] [--modpack-zip=PATH] [-o=DIR] [--results-file=FILE]
[--set-level-from=<levelFrom>] [--slug=<slug>]
[--ignore-missing-files=<ignoreMissingFiles>[,
|<nl><ignoreMissingFiles>...]]...
[--overrides-exclusions=<overridesExclusions>[NL or ,
<overridesExclusions>...]]... [[--exclude-include-file=FILE|URI]
[--exclude-all-mods] [[--excludes=PROJECT_ID|SLUG[,
|<nl>PROJECT_ID|SLUG...]]... [--force-includes=PROJECT_ID|SLUG[,
|<nl>PROJECT_ID|SLUG...]]...]] [[--use-http2] [--wiretap]]
[[--api-cache-ttl=OPERATION=DURATION]... [--api-cache-default-ttl=DURATION]]
[[--forge-promotions-url=URL] [--forge-maven-repo-url=URL]] [COMMAND]
Downloads, installs, and upgrades CurseForge modpacks
--api-base-url=<apiBaseUrl>
Allows for overriding the CurseForge Eternal API used
--api-cache-default-ttl=DURATION
Set default/fallback TTL in ISO-8601 duration format.
Default: P2D
--api-cache-ttl=OPERATION=DURATION
Set individual operation TTLs
--api-key=<apiKey> An API key allocated from the Eternal developer console at https://console.curseforge.com/
Can also be passed via CF_API_KEY
--api-key-file=PATH Read the API key from a UTF-8 file (instead of passing it directly).
Can also be passed via CF_API_KEY_FILE
--disable-api-caching
--downloads-repo=DIR A local directory that will supply pre-downloaded mod and modpack files that are marked
disallowed for automated download. The subdirectories mods, modpacks, and worlds will
also be consulted accordingly.
--exclude-all-mods Exclude all mods regardless of manifest contents
--exclude-include-file=FILE|URI
A JSON file that contains global and per modpack exclude/include declarations. See README
for schema.
--excludes, --exclude-mods=PROJECT_ID|SLUG[,|<nl>PROJECT_ID|SLUG...]
For mods that need to be excluded from server deployments, such as those that don't label
as client
--file-download-retries=COUNT
Default is 5
--file-download-retry-min-delay=DURATION
Default is PT5S
--file-id=<fileId>
--filename-matcher=STR Substring to select specific modpack filename, or a slash-surrounded string to be parsed
regex, E.G. '/.*1\.5$/'
--force-includes, --force-include-mods=PROJECT_ID|SLUG[,|<nl>PROJECT_ID|SLUG...]
Some mods incorrectly declare client-only support, but still need to be included in a
server deploy.
This can also be used to selectively override exclusions.
--force-reinstall-modloader
--force-synchronize
--forge-maven-repo-url=URL
URL for Forge Maven repository where installer is downloaded.
Can also be set via env var FORGE_MAVEN_REPO_URL
Default is https://maven.minecraftforge.net
--forge-promotions-url=URL
URL for Forge promotions JSON.
Can also be set via env var FORGE_PROMOTIONS_URL
Default is https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json
-h, --help
--ignore-missing-files=<ignoreMissingFiles>[,|<nl><ignoreMissingFiles>...]
These files will be ignored when evaluating if the modpack is up to date
--max-concurrent-downloads=<maxConcurrentDownloads>
Default is 10
--missing-mods-filename=<missingModsFilename>
--mod-loader-version=VERSION
Override the mod loader version specified in the modpack
--modpack-manifest=PATH
Similar to --modpack-zip but provide the manifest.json from the modpack.
Can be a local file path or a URL to a manifest.
--modpack-page-url=URL URL of a modpack page such as
https://www.curseforge.com/minecraft/modpacks/all-the-mods-8or a file's page
https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390
--modpack-zip=PATH Path to a pre-downloaded modpack client zip file that can be used when modpack author
disallows automation.
Can also be passed via CF_MODPACK_ZIP
-o, --output-directory=DIR
--overrides-exclusions=<overridesExclusions>[NL or ,<overridesExclusions>...]
Excludes files from the overrides that match these ant-style patterns
* : matches any non-slash characters
** : matches any characters
? : matches one character
--overrides-skip-existing
When enabled, existing files will not be replaced by overrides content from the modpack
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--set-level-from=<levelFrom>
When WORLD_FILE, a world file included the modpack will be unzipped into a folder under
'saves' and referenced as 'LEVEL' in the results file.
When OVERRIDES and the overrides contains a world save directory (contains level.dat),
then that directory will be referenced as 'LEVEL' in the results file.
In either case, existing world data will be preserved and skipped if it already exists.
Valid values: WORLD_FILE, OVERRIDES
--slug=<slug> The short-URL identifier
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Commands:
schemas Output relevant JSON schemas
Usage: mc-image-helper install-fabric-loader [-h] [--force-reinstall] [--fabric-meta-base-url=<fabricMetaBaseUrl>]
[--output-directory=DIR] [--results-file=FILE] [--from-local-file=FILE |
--from-url=URL | [[--installer-version=VERSION] [--loader-version=VERSION]
[--minecraft-version=VERSION]]] [[--use-http2] [--wiretap]]
Provides a few ways to obtain a Fabric loader with simple cleanup of previous loader instances
--fabric-meta-base-url=<fabricMetaBaseUrl>
Base URL for Fabric meta API. Default: https://meta.fabricmc.net
--force-reinstall Force reinstall of the loader even if it already exists
--from-local-file=FILE
--from-url=URL
-h, --help
--installer-version=VERSION
By default the latest installer version is used
--loader-version=VERSION
By default the latest launcher version is used
--minecraft-version=VERSION
--output-directory=DIR
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-forge [-h] [--clean-libraries] [--force-reinstall] [--minecraft-version=VERSION]
[--output-directory=DIR] [--results-file=FILE] [--forge-installer=FILE |
[--forge-version=<version>]] [[--use-http2] [--wiretap]]
[[--forge-promotions-url=URL] [--forge-maven-repo-url=URL]]
Downloads and installs a requested version of Forge
--clean-libraries Remove installed libraries not required by the Forge shim
--force-reinstall
--forge-installer=FILE
Use a local forge installer
--forge-maven-repo-url=URL
URL for Forge Maven repository where installer is downloaded.
Can also be set via env var FORGE_MAVEN_REPO_URL
Default is https://maven.minecraftforge.net
--forge-promotions-url=URL
URL for Forge promotions JSON.
Can also be set via env var FORGE_PROMOTIONS_URL
Default is https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json
--forge-version=<version>
A specific Forge version or to auto-resolve the version provide 'latest' or 'recommended'.
Default value is recommended
-h, --help
--minecraft-version=VERSION
'latest', which is the default, or a specific version
--output-directory=DIR
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-modrinth-modpack [--force-modloader-reinstall] [--force-synchronize]
[--api-base-url=<baseUrl>] [--default-exclude-includes=FILE|URI]
[--default-version-type=TYPE] [--game-version=<gameVersion>]
[--loader=<loader>]
[--max-concurrent-downloads=<maxConcurrentDownloads>]
[--output-directory=DIR] --project=<modpackProject>
[--results-file=FILE] [--version=<version>]
[--exclude-files=<excludeFiles>[,|<nl><excludeFiles>...]]...
[--force-include-files=<forceIncludeFiles>[,
|<nl><forceIncludeFiles>...]]...
[--ignore-missing-files=<ignoreMissingFiles>[,
|<nl><ignoreMissingFiles>...]]...
[--overrides-exclusions=<overridesExclusions>[NL or ,
<overridesExclusions>...]]... [[--use-http2] [--wiretap]]
[[--forge-promotions-url=URL] [--forge-maven-repo-url=URL]]
Supports installation of Modrinth modpacks along with the associated mod loader
--api-base-url=<baseUrl>
Default: https://api.modrinth.com
--default-exclude-includes=FILE|URI
A JSON file that contains global and per modpack exclude/include declarations. See README
for schema.
--default-version-type=TYPE
Valid values: release, beta, alpha (optional '+' suffix)
Default: release
--exclude-files=<excludeFiles>[,|<nl><excludeFiles>...]
Files to exclude, such as improperly declared client mods. Plain values match any part of
the file's name/path. Values surrounded by '/' are evaluated as Java regex patterns, E.G.
'/(^|/)figura-/'
Embedded comments are allowed.
--force-include-files=<forceIncludeFiles>[,|<nl><forceIncludeFiles>...]
Files to force include that were marked as non-server mods. Plain values match any part of
the file's name/path. Values surrounded by '/' are evaluated as Java regex patterns, E.G.
'/(^|/)figura-/'
Embedded comments are allowed.
--force-modloader-reinstall
--force-synchronize
--forge-maven-repo-url=URL
URL for Forge Maven repository where installer is downloaded.
Can also be set via env var FORGE_MAVEN_REPO_URL
Default is https://maven.minecraftforge.net
--forge-promotions-url=URL
URL for Forge promotions JSON.
Can also be set via env var FORGE_PROMOTIONS_URL
Default is https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json
--game-version=<gameVersion>
Applicable Minecraft version
Default: (any)
--ignore-missing-files=<ignoreMissingFiles>[,|<nl><ignoreMissingFiles>...]
These files will be ignored when evaluating if the modpack is up to date
--loader=<loader> Valid values: fabric, forge, quilt, neoforge
Default: (any)
--max-concurrent-downloads=<maxConcurrentDownloads>
Can also set env var MODRINTH_MAX_CONCURRENT_DOWNLOADS
Default is 10
--output-directory=DIR
--overrides-exclusions=<overridesExclusions>[NL or ,<overridesExclusions>...]
Excludes files from the overrides that match these ant-style patterns
* : matches any non-slash characters
** : matches any characters
? : matches one character
Embedded comments are allowed.
--project=<modpackProject>
One of
- Project ID or slug
- Project page URL
- Project file URL
- Custom URL of a hosted modpack file
- Local path to a modpack file
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--version, --version-id=<version>
Version ID, name, or number from the file's metadata
Default chooses newest file based on game version, loader, and/or default version type
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-neoforge [-h] [--force-reinstall] [--minecraft-version=VERSION] [--output-directory=DIR]
[--results-file=FILE] [--neoforge-installer=FILE |
[--neoforge-version=<version>]] [[--use-http2] [--wiretap]]
Downloads and installs a requested version of NeoForge
--force-reinstall
-h, --help
--minecraft-version=VERSION
'latest', which is the default, or a specific version to narrow NeoForge version selection
--neoforge-installer=FILE
Use a local neoforge installer
--neoforge-version=<version>
A specific NeoForge version, 'latest', or 'beta'. Default value is latest
--output-directory=DIR
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-oci-pack [-hV] [--artifact-type=<expectedArtifactType>] [--auth-file=FILE]
[--filename-strategy=<filenameStrategy>] [--layer-list-file=FILE]
[--layer-media-type=<expectedLayerMediaType>] --output-directory=DIR --ref=REF
Pulls an OCI artifact and writes its layer blobs to disk in apply order
--artifact-type=<expectedArtifactType>
The artifact type to expect in the manifest. Matching is done against the manifest's
artifactType or its config mediaType.
When set to an empty string or */*, then artifact type checking will be skipped.
Default: application/vnd.itzg.minecraft.modpack.v1+json
--auth-file=FILE Registry login JSON (root auths map). When unset, reads the default login file under the user
home directory if present.
--filename-strategy=<filenameStrategy>
How to name layer files on disk. Valid values: title, digest.
Default: title
-h, --help Show this help message and exit.
--layer-list-file=FILE
Write each pulled layer's absolute path on its own line to this file, in manifest layer order.
Suitable for `mapfile -t ... < FILE` in shell. When omitted, layer paths are also printed to
stdout for interactive use.
--layer-media-type=<expectedLayerMediaType>
Limit downloaded layers to those matching this media type.
When set to an empty string or */*, then media type checking will be skipped.
Default: application/vnd.itzg.minecraft.modpack.layer.v1.tar+gzip
--output-directory=DIR
Directory where layer blobs are written. Acts as a content-addressed cache between
invocations: layers whose digest already exists are not re-downloaded.
--ref=REF OCI reference, e.g. ghcr.io/owner/pack:v1 or ghcr.io/owner/pack@sha256:...
The optional oci:// prefix is tolerated.
-V, --version Print version information and exit.
Usage: mc-image-helper install-paper [-h] [--check-updates] [--clean-libraries] [--base-url=<baseUrl>]
[-o=<outputDirectory>] [--results-file=FILE] [--url=<downloadUrl> |
[[--project=<project>] [--build=<build>] [--channel=<channel>]
[--version=<version>]]] [[--use-http2] | [--wiretap]]
Installs selected PaperMC
--base-url=<baseUrl>
--build=<build>
--channel=<channel> This is ignored for now
--check-updates Check for updates and exit with status code 0 when available
--clean-libraries Remove currently installed and not required libraries
-h, --help
-o, --output-directory=<outputDirectory>
--project=<project>
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--url=<downloadUrl> Use a custom URL location
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--version=<version> May be 'latest' or specific version
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-purpur [--clean-libraries] [--base-url=<baseUrl>] [-o=<outputDirectory>]
[--results-file=FILE] [[[--build=<build>] [--version=<version>]] |
--url=<downloadUrl>] [[--use-http2] | [--wiretap]]
Downloads latest or selected version of Purpur
--base-url=<baseUrl>
--build=<build>
--clean-libraries Remove currently installed and not required libraries
-o, --output-directory=<outputDirectory>
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--url=<downloadUrl> Use a custom URL location
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--version=<version> May be 'latest' or specific version
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-quilt [-h] [--force-reinstall] [--loader-version=VERSION] [--minecraft-version=VERSION]
[--output-directory=DIR] [--repo-url=<repoUrl>] [--results-file=FILE]
[--installer-url=URL | --installer-version=VERSION] [[--use-http2] [--wiretap]]
Installs Quilt mod loader
--force-reinstall
-h, --help
--installer-url=URL
--installer-version=VERSION
Default uses latest
--loader-version=VERSION
Default uses latest
--minecraft-version=VERSION
'latest', 'snapshot', or specific version
--output-directory=DIR
--repo-url=<repoUrl> Default: https://maven.quiltmc.org/repository/release
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper install-vanilla [-h] [--force-reinstall] [--output-directory=DIR] [--results-file=FILE]
[--version=VERSION] [[--use-http2] [--wiretap]]
Downloads and installs a requested version of vanilla Minecraft
--force-reinstall
-h, --help
--output-directory=DIR
--results-file=FILE A key=value file suitable for scripted environment variables. Currently includes
SERVER: the entry point jar or script
VERSION: the resolved Minecraft version
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--version=VERSION the version of Minecraft to install; defaults to the latest release
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper interpolate [-h] ([--replace-env-prefix=<prefix>] [--replace-env-excludes=FILENAME[,
FILENAME...]]... [--replace-env-exclude-paths=PATH[,PATH...]]...
--replace-env-file-suffixes=PATH[,PATH...] [--replace-env-file-suffixes=PATH[,
PATH...]]...) [DIRECTORY...]
Interpolates existing files in one or more directories
[DIRECTORY...]
-h, --help Show this usage and exit
--replace-env-exclude-paths=PATH[,PATH...]
Destination paths that will be excluded from processing
--replace-env-excludes=FILENAME[,FILENAME...]
Filenames (without path) that should be excluded from processing.
--replace-env-file-suffixes=PATH[,PATH...]
Filename suffixes (without dot) that should be processed. For example: txt,json,yaml
--replace-env-prefix=<prefix>
Only placeholder variables with this prefix will be processed.
Default: CFG_
Usage: mc-image-helper java-release
Outputs the Java release number, such as 8, 11, 17
Usage: mc-image-helper manage-users [-fh] [--existing=<existingFileBehavior>]
[--mojang-api-base-url=<mojangApiBaseUrl>] [--output-directory=<outputDirectory>]
[--playerdb-api-base-url=<playerdbApiBaseUrl>] -t=<type>
[--user-api-provider=<userApiProvider>] [--version=<version>] [[--use-http2]
[--wiretap]] [INPUT[,INPUT...]...]
[INPUT[,INPUT...]...] One or more Mojang usernames, UUID, or ID (UUID without dashes); however, when offline,
only UUID/IDs can be provided.
When input is a file, only one local file path or URL can be provided
--existing=<existingFileBehavior>
Select the behavior when the resulting file already exists
Allowed: SYNCHRONIZE, MERGE, SKIP
-f, --input-is-file
-h, --help
--mojang-api-base-url=<mojangApiBaseUrl>
--output-directory=<outputDirectory>
--playerdb-api-base-url=<playerdbApiBaseUrl>
-t, --type=<type> Allowed: JAVA_WHITELIST, JAVA_OPS
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--user-api-provider=<userApiProvider>
Allowed: mojang, playerdb
--version=<version> Minecraft game version. If not provided, assumes JSON format
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper maven-download [-h] [--print-filename] [--skip-existing] [--skip-up-to-date] -a=<artifact>
[--classifier=<classifier>] -g=<group> [--output-directory=<outputDirectory>]
[--packaging=<packaging>] [-r=<mavenRepo>] [-v=<version>] [[--use-http2]
[--wiretap]]
Downloads a maven artifact from a Maven repository
-a, -m, --module, --artifact=<artifact>
--classifier=<classifier>
-g, --group=<group>
-h, --help
--output-directory=<outputDirectory>
--packaging=<packaging>
--print-filename
-r, --maven-repo=<mavenRepo>
--skip-existing
--skip-up-to-date
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
-v, --version=<version> A specific version, 'release', or 'latest'
Default: release
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper mcopy [-hz] [--file-is-listing] [--ignore-missing-sources] [--quiet-when-skipped]
[--skip-existing] [--glob=GLOB] [--max-concurrent-sources=<maxConccurentSources>]
[--scope=<manifestId>] --to=<dest> [[--use-http2] [--wiretap]] [SRC[,|<nl>SRC...]...]
Multi-source file copy operation with with managed cleanup. Supports auto-detected sourcing from file list,
directories, and URLs
[SRC[,|<nl>SRC...]...] Any mix of source file, directory, or URLs delimited by commas or newlines
Per-file destinations can be assigned by destination<source
Embedded comments are allowed.
--file-is-listing Source files or URLs are processed as a line delimited list of sources.
For remote listing files, the contents must all be file URLs.
--glob=GLOB When a source is a directory, this filename glob will be applied to select files.
-h, --help
--ignore-missing-sources
Don't log or fail exit code when any or all sources are missing
--max-concurrent-sources=<maxConccurentSources>
Maximum number of sources to process concurrently
--quiet-when-skipped Don't log when file exists or is up to date
--scope, --manifest-id=<manifestId>
If managed cleanup is required, this is the identifier used for qualifying manifest
filename in destination
--skip-existing Skips a download when the destination file already exists.
If enabled, then --skip-up-to-date is ignored.
--to, --output-directory=<dest>
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
-z, --skip-up-to-date Skips a download when the destination file is already up to date.
The remote server is queried with If-Modified-Since request header
and checks Last-Modified response header.
Usage: mc-image-helper modrinth [--skip-existing] [--skip-up-to-date] [--allowed-version-type=<defaultVersionType>]
[--api-base-url=<baseUrl>] [--download-dependencies=<downloadDependencies>]
--game-version=<gameVersion> --loader=<loader> [--output-directory=DIR]
[--world-directory=<worldDirectory>] [--projects=[loader:]id|slug[?][:version][,|<nl>
[loader:]id|slug[?][:version]...]]... [[--use-http2] [--wiretap]]
Automates downloading of modrinth resources
--allowed-version-type=<defaultVersionType>
Valid values: release, beta, alpha (optional '+' suffix)
--api-base-url=<baseUrl>
Default: https://api.modrinth.com
--download-dependencies=<downloadDependencies>
Default is NONE
Valid values: NONE, REQUIRED, OPTIONAL
--game-version=<gameVersion>
Applicable Minecraft version
--loader=<loader> Valid values: fabric, quilt, forge, neoforge, bukkit, spigot, paper, folia, pufferfish, leaf,
purpur, bungeecord, velocity, datapack
--output-directory=DIR
--projects=[loader:]id|slug[?][:version][,|<nl>[loader:]id|slug[?][:version]...]
Project ID or Slug. Can be <project ID>|<slug>, <loader>:<project ID>|<slug>, <loader>:
<project ID>|<slug>:<version ID|version number|release type>, '@'<filename with ref per
line (supports # comments)>
Append '?' to mark a project as optional (skipped with a warning if unavailable).
Examples: fabric-api, fabric:fabric-api, fabric:fabric-api:0.76.1+1.19.2, datapack:terralith,
pl3xmap?, @/path/to/modrinth-mods.txt
Valid release types: release, beta, alpha
Valid loaders: fabric, forge, paper, datapack, etc.
Embedded comments are allowed.
--skip-existing
--skip-up-to-date
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
--world-directory=<worldDirectory>
Used for datapacks, a path relative to the output directory or an absolute path
Default: world
Usage: mc-image-helper network-interfaces [--include-loopback] [--check=<ifNameToCheck>]
Provides simple operations to list network interface names and check existence
--check=<ifNameToCheck>
--include-loopback
Usage: mc-image-helper patch [-h] [--json-allow-comments] [--patch-env-prefix=<envPrefix>] FILE_OR_DIR
Patches one or more existing files using JSON path based operations
Supports the file formats:
- JSON
- JSON5
- Yaml
- TOML, but processed output is not pretty
- Properties, but comments are not retained
FILE_OR_DIR Path to a PatchSet or PatchDefinition json file, or directory containing PatchDefinition json files
-h, --help Show this usage and exit
--json-allow-comments
Whether to allow comments in JSON files. Env: PATCH_JSON_ALLOW_COMMENTS
Default: true
--patch-env-prefix=<envPrefix>
Only placeholder variables with this prefix will be processed
Default: CFG_
Usage: mc-image-helper resolve-minecraft-version [[--use-http2] [--wiretap]] <inputVersion>
Resolves and validate latest, snapshot, and specific versions
<inputVersion>
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper set-properties [--escape-unicode] [--definitions=<propertyDefinitionsFile>]
[-p=<String=String>]... <propertiesFile> [COMMAND]
Maps environment variables to a properties file
<propertiesFile>
--definitions=<propertyDefinitionsFile>
JSON file of property names to PropertyDefinition mappings
--escape-unicode
-p, --custom-property, --custom-properties=<String=String>
Key=value pairs of custom properties to set
Commands:
schema Output JSON schema for property definitions
Usage: mc-image-helper show-all-subcommand-usage [--usage-width=<usageWidth>] [COMMAND]
Renders all of the subcommand usage as markdown sections for README
--usage-width=<usageWidth>
Width of the usage help output
Default is 120
Commands:
check-readme Checks that README command documentation is current; exits with 1 if out of date
update-readme Updates the generated command documentation in README
Usage: mc-image-helper sync [-h] [--skip-newer-in-destination] <srcDest>[,|<nl><srcDest>...] <srcDest>[,
|<nl><srcDest>...]...
Synchronizes the contents of one directory to another.
<srcDest>[,|<nl><srcDest>...] <srcDest>[,|<nl><srcDest>...]...
src... dest directories
-h, --help Show this usage and exit
--skip-newer-in-destination
Skip any files that exist in the destination and have a newer modification time than the source.
Usage: mc-image-helper sync-and-interpolate [-h] [--skip-newer-in-destination] ([--replace-env-prefix=<prefix>]
[--replace-env-excludes=FILENAME[,FILENAME...]]...
[--replace-env-exclude-paths=PATH[,PATH...]]...
--replace-env-file-suffixes=PATH[,PATH...] [--replace-env-file-suffixes=PATH
[,PATH...]]...) <srcDest>[,|<nl><srcDest>...] <srcDest>[,
|<nl><srcDest>...]...
Synchronizes the contents of one directory to another with conditional variable interpolation.
<srcDest>[,|<nl><srcDest>...] <srcDest>[,|<nl><srcDest>...]...
src... dest directories
-h, --help Show this usage and exit
--replace-env-exclude-paths=PATH[,PATH...]
Destination paths that will be excluded from processing
--replace-env-excludes=FILENAME[,FILENAME...]
Filenames (without path) that should be excluded from processing.
--replace-env-file-suffixes=PATH[,PATH...]
Filename suffixes (without dot) that should be processed. For example: txt,json,yaml
--replace-env-prefix=<prefix>
Only placeholder variables with this prefix will be processed.
Default: CFG_
--skip-newer-in-destination
Skip any files that exist in the destination and have a newer modification time than the source.
Usage: mc-image-helper test-logging-levels
Usage: mc-image-helper toml-path [--file=FILE] query
Extracts a path from a TOML file using json-path syntax
query JSON path expression where root element $ can be omitted
--file=FILE A TOML file to query. If not set, reads stdin
Usage: mc-image-helper vanillatweaks [--force-synchronize] [--base-url=<baseUrl>] [--output-directory=DIR]
[--world-subdir=<worldSubdir>] [--pack-files=FILE[,|<nl>FILE...]]...
[--share-codes=CODE[,|<nl>CODE...]]... [[--use-http2] [--wiretap]]
Downloads Vanilla Tweaks resource packs, data packs, or crafting tweaks given a share code or pack file
--base-url=<baseUrl>
--force-synchronize
--output-directory=DIR
--pack-files=FILE[,|<nl>FILE...]
--share-codes=CODE[,|<nl>CODE...]
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
--world-subdir=<worldSubdir>
Usage: mc-image-helper version-from-modrinth-projects [--allowed-version-type=<defaultVersionType>]
[--api-base-url=<baseUrl>] [--loader=<loader>] [--projects=
[loader:]id|slug[?][:version][,|<nl>[loader:]id|slug[?][:
version]...]...]... [[--use-http2] [--wiretap]]
Finds a compatible Minecraft version across given Modrinth projects
--allowed-version-type=<defaultVersionType>
Valid values: release, beta, alpha
--api-base-url=<baseUrl>
Default: https://api.modrinth.com
--loader=<loader> Valid values: fabric, quilt, forge, neoforge, bukkit, spigot, paper, folia, pufferfish, leaf,
purpur, bungeecord, velocity, datapack
--projects=[loader:]id|slug[?][:version][,|<nl>[loader:]id|slug[?][:version]...]...
Project ID or Slug. Can be <project ID>|<slug>, <loader>:<project ID>|<slug>, <loader>:
<project ID>|<slug>:<version ID|version number|release type>, '@'<filename with ref per
line (supports # comments)>
Append '?' to mark a project as optional (excluded from version resolution).
Examples: fabric-api, fabric:fabric-api, fabric:fabric-api:0.76.1+1.19.2, datapack:terralith,
pl3xmap?, @/path/to/modrinth-mods.txt
Valid release types: release, beta, alpha
Valid loaders: fabric, forge, paper, datapack, etc.
--use-http2 Whether to use HTTP/2.
Default: true
Env: FETCH_USE_HTTP2
--wiretap Whether to enable Reactor Netty wiretap logging. Make sure to set logging level to trace.
Default: false
Env: FETCH_WIRETAP
Usage: mc-image-helper yaml-path [--file=<yamlFile>] <yamlPath>
Extracts a path from a YAML file using json-path syntax
<yamlPath> A YAML/JSON path in to query. Leading root anchor, $, will be added if not present
--file=<yamlFile> A YAML file to query
$schema: optional JSON Schema reference used by editors for completion and validation; ignored by the patch processor.patches: array of PatchDefinition
Example
{
"$schema": "https://itzg.github.io/mc-image-helper/schemas/patch-set.json",
"patches": [
{
"file": "/data/paper.yml",
"ops": [
{
"$set": {
"path": "$.verbose",
"value": true
}
},
{
"$set": {
"path": "$.settings['velocity-support'].enabled",
"value": "${CFG_VELOCITY_ENABLED}",
"value-type": "bool"
}
},
{
"$put": {
"path": "$.settings",
"key": "my-test-setting",
"value": "testing"
}
}
]
}
]
}$schema: optional JSON Schema reference used by editors for completion and validation; ignored by the patch processor.file: Path to the file to patchfile-format: optional If non-null, declares a specifically supported format name: json, json5, yaml, toml, properties. Otherwise, the file format is detected by the file's suffix.ops: array of PatchOperation
Example:
{
"$schema": "https://itzg.github.io/mc-image-helper/schemas/patch-definition.json",
"file": "/data/paper.yml",
"ops": [
{
"$set": {
"path": "$.verbose",
"value": true
}
},
{
"$set": {
"path": "$.settings['velocity-support'].enabled",
"value": "${CFG_VELOCITY_ENABLED}",
"value-type": "bool"
}
},
{
"$put": {
"path": "$.settings",
"key": "my-test-setting",
"value": "testing"
}
}
]
}Each patch operation object contains a single key that one is one of the following sections and then an object within each. For example { "$set" : { ... } }.
The $set operation can set an existing field to a new value. If a new field needs to be added, use the $put operation.
$set
Example:
{
"$set": {
"path": "$.verbose",
"value": true
}
}The $put operation can add or update a field with the given key within an object.
$putpath: The JSON path to the object containing key to setkey: The key to setvalue: The value to set. If the given value is a string, variable placeholders of the form${...}will be replaced from the environment variables and the resulting string can be converted by setting value-type.value-type: optional see below
Example:
{
"$put": {
"path": "$.settings",
"key": "my-test-setting",
"value": "testing"
}
}The $add operation allows for adding a value to an array.
$add
One of the following identifiers or can be prefixed with list of to indicate a list of the identified type:
- int : integer/whole value
- float : numerical value with an optional decimal part
- bool : boolean value of
trueorfalse - auto : where the text value is attempted to be converted into one of the above
For CurseForge packs, modpacks.<slug>.overridesExclusions accepts ant-style paths relative to the overrides directory. These patterns are combined with --overrides-exclusions; * matches non-slash characters, ** matches across directories, and ? matches one character. Project excludes and forceIncludes continue to accept slugs or IDs and do not filter bundled override files. Use --force-synchronize to reapply changed patterns to an existing installation.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Mods Exclude/Include File Content",
"type": "object",
"additionalProperties": false,
"properties": {
"globalExcludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to exclude for all modpacks"
},
"globalForceIncludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to force include for all modpacks"
},
"modpacks": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/ExcludeIncludes"
},
"description": "Specific exclude/includes by modpack slug"
}
},
"definitions": {
"ExcludeIncludes": {
"type": "object",
"additionalProperties": false,
"properties": {
"excludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to exclude for this modpack"
},
"forceIncludes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mods by slug|id to force include for this modpack"
},
"overridesExclusions": {
"type": "array",
"items": {
"type": "string"
},
"description": "CurseForge override paths to exclude for this modpack, using ant-style patterns"
}
}
}
}
}{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Property Definition",
"type" : "object",
"additionalProperties" : false,
"properties" : {
"env" : {
"type" : "string"
},
"allowed" : {
"type" : "array",
"items" : {
"type" : "string"
}
},
"mappings" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"remove" : {
"type" : "boolean"
},
"translateLiteralNewlines" : {
"type" : "boolean"
}
},
"required" : [ "remove", "translateLiteralNewlines" ]
}Usage: mc-image-helper archive [-h] [COMMAND]
Archive helpers, checking for path traversal and extracting archives
-h, --help
Commands:
check-path-traversal Checks if an archive contains path traversal attack
extract Extracts an archive, checking for path traversal
Checks that the archive does not contain a Path Traversal Attack / Zip Slip.
Usage: mc-image-helper archive check-path-traversal ARCHIVE
Checks if an archive contains path traversal attack
ARCHIVE Path to archive
Usage: mc-image-helper archive extract [--overwrite] ARCHIVE DESTINATION
[FILE...]
Extracts an archive, checking for path traversal
ARCHIVE Path to archive
DESTINATION Output destination
[FILE...] Exact archive file paths to extract; extracts everything
when omitted
--overwrite Overwrite existing files
- Supported formats are ZIP, TAR, TAR.GZ, TAR.BZ2, and TAR.ZST.
- File arguments must exactly match paths inside the archive, including case. Wildcards and directory selection are not supported.
- Extracted files retain their archive paths. For example,
config/server.propertiesis written beneath the destination asconfig/server.properties. - Existing files are skipped unless
--overwriteis supplied.
Extract an entire ZIP archive into a directory:
mc-image-helper archive extract server.zip ./serverExtract a compressed TAR archive, replacing existing files:
mc-image-helper archive extract --overwrite server.tar.gz ./serverExtract a single file:
mc-image-helper archive extract server.zip ./server config/server.propertiesExtract multiple files, quoting names that contain spaces:
mc-image-helper archive extract server.tar.zst ./server \
config/server.properties \
"mods/example mod.jar"Forward file arguments from a Bash script or function:
mc-image-helper archive extract --overwrite -- "${src}" "${destDir}" "$@"The -- ends option parsing, allowing subsequent paths to begin with -.
If "$@" contains no arguments, the entire archive is extracted.