java-cli-script

Create or maintain a zero-dependency, single-file executable Java script using $ARGUMENTS. Apply all rules below strictly.

Purpose

These are self-contained, single-file Java scripts installed in a PATH directory (e.g., /usr/local/bin) and invoked like any shell command — no project structure, no build tool, no .java extension.

Composition

• Follow /java-conventions for all generic Java 25 style, syntax, naming, methods, streams, exceptions, and comments
• The rules below specialize /java-conventions for single-file source-mode scripts; when this skill is silent on a topic, /java-conventions applies

Single-File Constraint

• Everything lives in one file — all logic, records, enums, sealed types, and helper methods
• If the script grows beyond what fits comfortably in a single file, suggest switching to the java-cli-app skill instead
• No multi-file source-code programs — this skill is strictly for single-file scripts

Build

• Use Java 25 source-file mode — no build tool, no compilation step
• Never use the .java extension — scripts are executable files with a lowercase filename and a shebang
• Never use --enable-preview in the shebang — Java 25 is a GA release, all features used here are standard
• The shebang line is always:

#!/usr/bin/env -S java --source 25

• Save with a short, descriptive, lowercase command name (e.g., jsonformat, portcheck, sysinfo)
• Never use dashes in filenames (e.g., hello-world) — Java source-file mode does not support them. Use camelCase instead (e.g., helloWorld)
• Mark executable: chmod +x scriptname
• Install by copying or symlinking to a PATH directory: cp scriptname /usr/local/bin/ or ln -s $(pwd)/scriptname /usr/local/bin/scriptname

Script Structure

A minimal script:

#!/usr/bin/env -S java --source 25

void main(String... args) throws Exception {
    // ...
}

Naming Convention

• The script's filename is its application name — use it consistently in all output: version strings, help text, usage lines, and error messages
• Derive the application name dynamically at startup using MethodHandles.lookup().lookupClass().getName() — in source-file mode, the class name matches the filename, so there is nothing to hardcode or keep in sync