Command-Line Options Reference

Minimum Input Required for a Normal Build

--input <JAR|DIR>

Or use positional input

[JAR|DIR]

Input source: either a single JAR or a directory containing JAR files.

Positional alternative to --input. The two forms are mutually exclusive.

Application Identity

--name <NAME>

Application display name. Used in Windows metadata and Snug's per-user application identity.

--company <COMPANY>

Company or vendor name. Used in Windows metadata and Snug's per-user application identity.

Output

-o, --output <EXE>

Output Windows executable path. If omitted for a single-JAR build, Snug uses the JAR filename as the basis for the .exe name.

Application Metadata
--version <VERSION>

Application version. Accepts one to four numeric components, each from 0 to 65535. Missing trailing components default to zero.

--description <TEXT>

Windows FileDescription metadata.

--copyright <TEXT>

Windows LegalCopyright metadata.

--update-url <URL>

Adds a clickable "Check for a newer version" link to launcher error dialogs.

--icon <PNG/ICO>

PNG or ICO file used as the Windows executable icon.

Java Runtime

--min-java <N>

Minimum required Java major version. Default: 25.

--main-class <CLASS>

Overrides the Main-Class read from the JAR manifest.

--jvm-arg <OPTION>

Extra JVM option passed when the JVM is created. Repeatable.

Windows Resources

--manifest <XML>

Windows application manifest embedded as RT_MANIFEST.

--splash <PNG>

PNG splash image shown by the native launcher before the JVM starts.

--splash-ms <MS>

Minimum splash duration in milliseconds. Default: 1500.

--splash-max <WxH|off>

Recommended maximum splash dimensions used for a build-time warning. Default: 640x360. The setting does not resize the image.

Runtime Behaviour and Localisation

--download-jdk <off|auto|force>

Controls Snug's managed Java-runtime download behaviour. Default: auto.

Use off only when a compatible runtime will already be available on the target computer.

--localisation <TXT|DIR>

Embeds launcher localisation bundles. May be repeated for individual files or supplied with a directory containing snug-localisations.<tag>.txt files.

--allow-multiple-instances

Allows more than one copy of the packaged application to run at the same time. By default, Snug applications are single-instance.

Build and Diagnostic Tools

--dry-run

Validates inputs and reports what would be built without writing an executable.

--find-main

Lists classes in the input JAR or JARs that declare public static void main(String[]) and identifies the main class Snug would use when applicable.

--emit-payload

Writes the encoded embedded payload to standard output instead of building an executable.

--list-tokens

Lists all tokens that can be used in the localisation files for replacement.

Snug Tooling Options

--snug-version

Prints Snug's own version and exits.

--options <PATH>

Selects one options file instead of automatic lookup. See the detailed --options entry for lookup order and precedence.

--init-options [<PATH>]

Writes Snug's embedded example options file and exits. If no path is supplied, the default is ./snug.options.

--init-options-force

Allows --init-options to overwrite an existing destination file.

--init-options-stdout

Prints the example options configuration to standard output instead of writing a file.

-h, --help

Prints Snug's command-line help.

Option name, aliases, and short or long forms

Importance

A brief description of what the option does

Repeatability

Where to Use

Syntax

The option followed by its value, if required. Angle brackets mark a value to supply; square brackets mark an optional value.

When to use

A description of when to use this option

If omitted

What happens when the option is absent from both the command line and the loaded options files, including any default or build requirement.

Example

An example of the option and any parameter values

Important note

Constraints, interactions, or cautions to consider when using the option.

--input

Required input

Selects the JAR file or directory of JAR files that Snug should package.

Single

Both

Syntax

--input <JAR|DIR>

When to use

Use it when you want the input source to be explicit, especially in snug.options.

If omitted

Packaging fails if neither --input nor positional input supplies a JAR file or directory.

Example

--input build\libs\my-app.jar

Important note

The positional [JAR|DIR] form is also accepted in an options file. For clarity, this book recommends using --input in snug.options.

--name

Recommended

Sets the application's display name, used in Windows metadata and Snug's local application identity.

Single

Both

Syntax

--name <NAME>

When to use

Always set this to the real application name for a normal build.

If omitted

Snug uses the input JAR filename without its .jar extension, or the input directory name.

Example

--name "My Application Name"

Important note

Together with --company, this value identifies the application in Windows metadata and Snug’s application cache.

--company

Recommended

Sets the company or vendor name for Windows application identity.

Single

Both

Syntax

--company <COMPANY>

When to use

Always set this to the real company or vendor name for a normal build.

If omitted

Snug uses the resolved application name.

Example

--company "My Company"

Important note

Together with --name, this value identifies the application in Windows metadata and Snug’s application cache.

-o, --output

Recommended

Sets the path and filename of the Windows executable that Snug creates.

Single

Both

Syntax

--output <EXE>

When to use

Use it when you want to control the output filename or location.

If omitted

Snug chooses the default output name for the build which is based on the input JAR file(s) or directory name.

Example

--output dist\invoice-viewer.exe

Important note

If the destination executable already exists, Snug overwrites it.

--version

Recommended

Sets the Windows version number for the application identity.

Single

Both

Syntax

--version <VERSION>

When to use

Use it to give distributed builds a clear version number.

If omitted

Snug uses 0.0.0.0 as the application version.

Example

--version 1.2.0

Important note

The version may contain one to four numeric components, each from 0 to 65535.

--description

Recommended

Sets the Windows FileDescription metadata.

Single

Both

Syntax

--description <TEXT>

When to use

Use it to give the executable a meaningful description in Windows properties.

If omitted

Snug uses the application name as the Windows FileDescription.

Example

--description "Invoice Viewer"

Important note

This affects metadata only; it does not change the application's display name.

--copyright

Optional

Sets the Windows LegalCopyright metadata for the application identity.

Single

Both

Syntax

--copyright <TEXT>

When to use

Use it when you want copyright information embedded in the executable.

If omitted

No custom LegalCopyright value is supplied.

Example

--copyright "Copyright 2026 Example Pty Ltd"

Important note

This is informational metadata and does not provide legal protection by itself.

--update-url

Optional

Adds a clickable "Check for a newer version" link to launcher error dialogs.

Single

Both

Syntax

--update-url <URL>

When to use

Use it when users should have an easy path to a download or update page.

If omitted

Launcher dialogs do not include an update link.

Example

--update-url https://example.com/downloads

Important note

Use a stable HTTPS page where users can find an updated version of your application. Snug does not check whether the page exists or provides a download. This option adds a link to the launcher's error dialog; it does not download or install application updates.

--icon

Optional

Sets the icon embedded in the application executable.

Single

Both

Syntax

--icon <PNG/ICO>

When to use

Use it for a branded application icon.

If omitted

The default Snug application icon is used.

Example

--icon snug\icon.png

Important note

This option affects the built application, unlike snug_preview.exe --icon, which affects preview dialogs only.

--manifest

Optional

Embeds a Windows application manifest as RT_MANIFEST.

Single

Both

Syntax

--manifest <XML>

When to use

Use it only when the application needs a custom Windows manifest.

If omitted

No custom manifest file is embedded.

Example

--manifest snug\app.manifest

Important note

Snug checks that the supplied manifest is well-formed XML and rejects malformed XML during the build. This check does not confirm that the manifest contains valid or appropriate Windows application settings.

You remain responsible for the manifest's contents. Test the finished executable on the Windows systems you intend to support.

--main-class

Optional

Overrides the Main-Class that Snug would otherwise use in the manifest.

Single

Both

Syntax

--main-class <CLASS>

When to use

Use it when discovery is ambiguous or you intentionally want a different entry point.

If omitted

Snug uses its normal main-class detection behaviour.

Example

--main-class com.example.Launcher

Important note

The class must be a valid application entry point available in the packaged JARs.

At packaging time, use --find-main with the input JAR or directory to inspect candidate entry points.

--find-main

Optional

Lists classes that declare public static void main(String[]) and identifies the main class Snug would use when applicable.

Single

CLI only

Syntax

--find-main

When to use

Use it when you need to inspect or troubleshoot application entry points.

If omitted

Snug proceeds with its normal main-class handling.

Example

--find-main

Important note

This is a diagnostic command and does not replace --main-class when you intentionally need an override.

--min-java

Optional

Sets the minimum Java major version required by the application.

Single

Both

Syntax

--min-java <N>

When to use

Use it when the application requires a Java version different from the default.

If omitted

Snug will set the minimum Java version to Java 25.

Example

--min-java 25

Important note

Choose the lowest Java major version that the application genuinely requires.

--jvm-arg

Optional

Passes an option directly to the JVM when Snug creates it.

Multiple

Both

Syntax

--jvm-arg <OPTION>

When to use

Use it only when the Java application requires a specific JVM option, such as a memory limit or system property.

If omitted

The JVM starts without any additional options supplied by Snug.

Example

--jvm-arg=-Xmx2g

Important note

Invalid or unsupported JVM arguments can prevent the Java runtime from starting.

--download-jdk

Optional

Controls Snug's managed Java-runtime download behaviour.

Single

Both

Syntax

--download-jdk <off|auto|force>

When to use

Use it to control runtime downloads. Normally keep auto. Use force to exercise the managed-runtime path; a compatible Snug-managed cached runtime may still be reused.

If omitted

Snug uses automatic runtime discovery and download behaviour - i.e. the value is set to auto.

Example

--download-jdk=force

Important note

Using off can leave the application unable to start on a machine without a compatible Java runtime.

--cache-dir

Optional

Overrides the application's default per-user cache location.

Single

Both

Syntax

--cache-dir <ABSOLUTE_DIR>

When to use

Only when a deployment has a compelling storage requirement.

If omitted

On Windows, Snug normally stores application JARs under %LOCALAPPDATA%\snug\<company>\<app>\.

Example

--cache-dir "D:\ApplicationCache"

Important note

Use an absolute path. The directory need not exist at build time, but it must be usable on the target computer. This setting changes the application-JAR cache, not the separate managed-JDK cache.

--splash

Optional

Sets the PNG splash image shown by the launcher before the JVM starts.

Single

Both

Syntax

--splash <PNG>

When to use

Use it when you want a branded launcher splash while Java starts.

If omitted

The launcher starts without the custom splash image.

Example

--splash snug\splash.png

Important note

This is the Snug launcher splash, separate from JVM or JavaFX splash mechanisms.

--splash-ms

Optional

Sets the minimum time the Snug splash remains visible.

Single

Both

Syntax

--splash-ms <MS>

When to use

Use it when the splash should remain visible for at least a specific duration.

If omitted

Snug uses the default minimum duration of 1500 ms - i.e. 1.5 seconds.

Example

--splash-ms 2000

Important note

This is a minimum duration, not a guarantee that the startup will finish at that time.

--splash-max

Optional

Sets the recommended maximum splash dimensions used for a build-time warning.

Single

Both

Syntax

--splash-max <WxH|off>

When to use

Use it to change or disable the splash-size warning threshold.

If omitted

Snug uses the default 640x360 recommendation.

Example

--splash-max 800x450

Important note

This option does not resize the image. If the image exceeds the configured dimensions, Snug displays a build-time warning and continues packaging the application.

--allow-multiple-instances

Optional

Allows more than one copy of the application to run at the same time.

Single

Both

Syntax

--allow-multiple-instances

When to use

Use it only when separate simultaneous copies of the application are genuinely useful.

If omitted

If the application is already running, Snug activates the existing instance instead of starting another copy.

Example

--allow-multiple-instances

Important note

For most desktop and business applications, leaving the default single-instance behaviour in place is simpler for users.

--localisation

Optional

Embeds launcher localisation bundles.

Multiple

Both

Syntax

--localisation <TXT|DIR>

When to use

Use it to add translated or customised launcher messages.

If omitted

Only the built-in English launcher messages are available.

Example

--localisation snug\localisations

Important note

Files may be supplied individually, or a directory may contain snug-localisations.<tag>.txt files.

--list-tokens

Optional

Lists the built-in English message keys and the replacement tokens used by each key.

Single

CLI only

Syntax

--list-tokens

When to use

Use it when editing localisation messages to check which replacement tokens are available for each message key.

If omitted

Normal command processing continues.

Example

--list-tokens

Important note

This help command displays information without building the artefact. See Section 5: Customising Launcher Messages.

--init-localisations

Optional

Creates starter localisation files and exits without building an application.

Single

CLI only

Syntax

--init-localisations [DIR]

When to use

To create English message files and optional translation templates.

If omitted

No localisation files are generated.

Example

--init-localisations

Important note

The built-in English baseline is generated; use --init-localisations-tag to add language templates.

--init-localisations-tag

Optional

Adds a language template when generating localisation files.

Multiple

CLI only

Syntax

--init-localisations-tag <TAG>

When to use

With --init-localisations, to scaffold additional language files.

If omitted

Only the English baseline is generated.

Example

--init-localisations --init-localisations-tag de

Important note

Templates initially contain English values; translating them is a separate step.

--init-localisations-force

Optional

Allows --init-localisations to overwrite existing localisation template files.

Single

CLI only

Syntax

--init-localisations-force

When to use

Only when deliberately replacing previously generated translation files.

If omitted

Existing files remain protected from overwrite.

Example

--init-localisations --init-localisations-force

Important note

Overwriting files can discard customised translations.

--init-localisations-stdout

Optional

Prints generated localisation templates to standard output.

Single

CLI only

Syntax

--init-localisations-stdout

When to use

For inspection, scripting, or piping generated message templates.

If omitted

Templates are written to the selected directory.

Example

--init-localisations --init-localisations-stdout

Important note

This is a scaffolding command and does not package an application.

--options

Optional

Selects an options file explicitly.

Single

CLI only

Syntax

--options <PATH>

When to use

Use it when the configuration file has a different name or location.

If omitted

Snug reads snug.options, then snug.windows.options on Windows, from the current working directory. Missing automatic files are skipped. The directory containing snug.exe is not searched.

Example

--options config\release.options

Important note

An explicit --options file is used alone. Command-line single-value settings take precedence; repeatable --jvm-arg and --localisation values accumulate.

--init-options

Optional

Writes Snug's embedded example options file and exits.

Single

CLI only

Syntax

--init-options [<PATH>]

When to use

Use it to create a starter options file. (snug.options)

If omitted

No example options file is generated.

Example

--init-options

Important note

Snug will not overwrite an existing options file unless you also supply --init-options-force.

--init-options-force

Optional

Allows --init-options to overwrite an existing destination file.

Single

CLI only

Syntax

--init-options-force

When to use

Use it only with --init-options when replacing an existing options file is intentional.

If omitted

Snug protects an existing destination from being overwritten by --init-options.

Example

--init-options --init-options-force

Important note

This option is deliberately explicit because overwriting an options file can discard local configuration.

--init-options-stdout

Optional

Prints the example options configuration to standard output instead of writing a file.

Single

CLI only

Syntax

--init-options-stdout

When to use

Use it when you want to inspect or redirect the example configuration without creating a file.

If omitted

--init-options writes to its normal destination instead.

Example

--init-options --init-options-stdout

Important note

This is useful for scripting or comparing the embedded example configuration with an existing file.

--dry-run

Optional

Prepares and validates the payload, then reports what would be built without writing an executable.

Single

CLI only

Syntax

--dry-run

When to use

Use it to check configuration before performing a real build.

If omitted

Snug performs the normal build.

Example

--dry-run

Important note

A successful dry run does not prove that the final build or application launch will succeed. Icon loading and manifest XML checks occur later, during resource stamping.

--emit-payload

Optional

Writes the encoded embedded payload to standard output instead of building an executable.

Single

CLI only

Syntax

--emit-payload

When to use

Use it for low-level diagnostics or tooling around Snug's embedded payload.

If omitted

Snug performs the normal build.

Example

--emit-payload

Important note

This is an advanced diagnostic option and is not normally needed for application packaging.

--snug-version

Optional

Prints Snug's own version and exits.

Single

CLI only

Syntax

--snug-version

When to use

Use it when checking which Snug build is installed.

If omitted

Snug continues with normal command processing.

Example

--snug-version

Important note

This reports the Snug tool version, not the packaged application's --version value.

-h, --help

Optional

Displays Snug's command-line help and exits.

Single

CLI only

Syntax

--help

Or

-h

When to use

Use it to check the options supported by the installed version of Snug.

If omitted

Snug continues with normal command processing.

Example

--help

Or

-h

Important note

The built-in help is the definitive reference for the version of snug.exe you are running.

--icon

Optional

Changes the icon shown in Snug Preview dialogs.

Single

CLI only

Syntax

--icon <PNG/ICO>

When to use

Use it when you want the preview dialogs to show your application's own icon rather than the Snug Preview icon.

If omitted

Preview dialogs continue to use the built-in Snug Preview icon.

Example

--icon snug\icon.png

Important note

This changes preview dialogs only, not a built application. The preview window keeps the Snug mascot and shows your icon beneath its magnifying glass. Supply --icon once; if repeated, the last value wins and a warning is printed.

--localisation

Optional

Loads localisation messages so Snug Preview can display launcher dialogs in additional languages.

Multiple

CLI only

Syntax

--localisation <FILE|DIR>

When to use

Use it when checking customised or translated launcher messages before building the application.

If omitted

Only the built-in English messages are available in the preview language selector.

Example

--localisation snug\localisations

Important note

Repeat the option for additional files or directories. Directories are scanned at the top level only. English remains available; supplying snug-localisations.en.txt replaces the built-in English baseline.

--help / -h

Optional

Displays the built-in help for snug_preview.exe.

Single

CLI only

Syntax

--help

Or


-h

When to use

Use it when you need to check the options supported by the installed version of Snug Preview.

If omitted

Snug Preview starts normally instead of displaying help.

Example

--help

Or

-h

Important note

Use snug_preview.exe --help to check the options supported by your installed preview version.