JBang Cheatsheet: Essential Commands & Directives

JBang transforms Java into a scriptable language with zero build tool setup required. Whether you are scripting CI/CD pipelines, prototyping REST APIs, or building CLI tools, this reference cheatsheet covers all essential JBang directives, CLI commands, and workflow tricks.

///usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 21
//DEPS org.jsoup:jsoup:1.18.3

public class Script {
    public static void main(String... args) {
        System.out.println("Running Java 21 script with JBang!");
    }
}

1. Installation Quick Reference

# SDKMAN! (Linux / macOS)
$ sdk install jbang

# Homebrew (macOS / Linux)
$ brew install jbangdev/tap/jbang

# Windows (Chocolatey / Scoop)
$ choco install jbang
$ scoop install jbang

# Universal Curl (Linux / macOS)
$ curl -s https://jbang.dev/installer.sh | bash

2. Script Directives Reference

JBang directives are special comments placed at the top of your Java source files to configure dependencies, JVM flags, compiler settings, and external resources.

3. CLI Commands Cheatsheet

Project Initialization & Templates

# Initialize a default Java script
$ jbang init script.java

# Initialize with Picocli CLI template
$ jbang init --template=cli mycli.java

# List all available built-in templates
$ jbang template list

Running & Executing Scripts

# Run a local script
$ jbang script.java arg1 arg2

# Run a remote script directly from URL or GitHub
$ jbang https://github.com/jbangdev/jbang-examples/blob/main/helloworld.java

# Run in debug mode (opens JPDA port 4004 for IDE connection)
$ jbang --debug script.java

# Run script targeting Java 21 explicitly
$ jbang --java 21 script.java

Building & Native Compilation

# Build JAR artifact without executing
$ jbang build script.java

# Compile into a standalone GraalVM native binary
$ jbang build --native script.java

IDE Integration (`jbang edit`)

# Open script in IntelliJ IDEA with automatic project generation
$ jbang edit --open=idea script.java

# Open script in VS Code
$ jbang edit --open=vscode script.java

App Catalog & Global Installation

# Install script as a global terminal application
$ jbang app install mycli.java

# Run an app installed from a GitHub catalog
$ jbang jbangdev/jbang-examples/helloworld

# List all locally installed JBang apps
$ jbang app list

Cache Management

# Clear JBang downloaded dependencies and compiled class caches
$ jbang cache clear

# Display cache directory locations and statistics
$ jbang cache info

4. Advanced Workflow Examples

A. Multi-File Script Structure

// File: Main.java
///usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 21
//SOURCES UserService.java

public class Main {
    public static void main(String... args) {
        new UserService().process();
    }
}

B. Running JBang in GitHub Actions CI/CD

name: Automation Task
on: [push]
jobs:
  run-script:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jbangdev/jbang-action@v1
        with:
          script: .github/scripts/DeployTask.java
          args: --env=production

Frequently Asked Questions (FAQs)

Q1: Where does JBang store downloaded dependencies and JDKs?

JBang stores downloaded artifacts and cached JDKs in the ~/.jbang directory (or %USERPROFILE%\.jbang on Windows).

Q2: How do I pass JVM memory flags at runtime?

Use the //JAVA_OPTIONS directive inside your script (e.g., //JAVA_OPTIONS -Xmx2g) or pass it on the command line: jbang --java-options="-Xmx2g" script.java.

Q3: Can JBang run Kotlin or Groovy scripts?

Yes! JBang supports Kotlin (.kt) and Groovy (.groovy) files natively alongside Java source files.

Conclusion

JBang bridges the gap between Java's robust enterprise ecosystem and the quick, flexible scripting capabilities needed for modern automation. Bookmark this cheatsheet for quick reference during your daily development workflows.