JBang Documentation

JBang is a tool designed to make Java scripting easy by removing traditional project setup overhead. It allows you to run Java files directly, manage dependencies via //DEPS declarations, and support multiple languages including .java, .jsh, .kt, .groovy, and .md.

Key capabilities include:

• Dependency Management: Automatic resolution of libraries.
• Native Images: Generation of native binaries using GraalVM.
• IDE Integration: Full editor support via jbang edit.
• Templates: Rapid scaffolding of new scripts.
• Aliases & Catalogs: Easy sharing and reuse of scripts.
• Cross-Platform: Support for Windows, macOS, Linux, and AIX.

You can use environment variables and system properties in your //DEPS declarations using the format ${[env.]propertyname:<defaultvalue>}.

JBang provides properties similar to os-maven-plugin (e.g., ${os.name}) and a specific property for JavaFX (${os.detected.jfxname}) to help make scripts portable across operating systems.

Example of using an OS-detected property:

//DEPS org.openjfx:javafx-graphics:11.0.2:${os.detected.jfxname}

Using jbang --interactive enables a REPL environment powered by jshell. This allows you to explore your script and its dependencies interactively.

When running Java/JAR scripts in interactive mode, JBang provides a userMain function. This function delegates to the script's main function. You can invoke it with arguments using userMain(args).

Note: jshell cannot access classes in the default package. You must add a package statement to your script/class to make it visible in the REPL.

For single-file programs, you can declare dependencies using //DEPS comments instead of a traditional build file (like pom.xml). JBang will resolve these from Maven Central or other configured repositories and add them to the classpath.

Example: CLI app with Picocli dependency

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS info.picocli:picocli:4.6.3
//JAVA 25+

import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Parameters;

@Command(name = "hello", mixinStandardHelpOptions = true)
class hello implements Runnable {
    @Parameters(index = "0", description = "The greeting to print")
    private String greeting;

    void main(String[] args) {
        new CommandLine(new hello()).execute(args);
    }

    public void run() {
        System.out.println("Hello " + greeting);
    }
}

If your IDE does not have dedicated JBang support, use the sandbox mode (-b or --sandbox) with the edit command.

In this mode, JBang generates a temporary project in a temporary location using symbolic links to your script. This allows most Java-based IDEs to treat the script as a standard project. JBang generates a build.gradle file and IDE-specific settings (currently for Eclipse and VS Code) to facilitate this.

JBang configuration can be applied at two scopes:

1. Global Scope: Applies to all JBang runs. Defaults are stored in ~/.jbang/jbang.properties.
2. Local Scope: Applies only within a specific directory tree. To create a local configuration, run jbang config set --file=<path> <key> <value> within that directory. This creates a local jbang.properties file that overrides global settings.

To inspect the origin and order of your configuration settings, use jbang config list --show-origin.

JBang uses special comments (directives) starting with // to configure compilation and execution. To ensure they are processed correctly, follow these rules:

• Directives must start at the beginning of a line with // (no leading whitespace).
• They must be placed in the first comment block of the file, before any actual code.
• They are case-sensitive.
• There must be no space between // and the directive name (e.g., use //DEPS, not // DEPS).
• They can appear multiple times if the directive supports it (like //DEPS).

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS com.example:library:1.0.0
//JAVA 17+
//PREVIEW

class MyScript {
    // ... your code
}

Templates can access values passed during initialization via the -Dkey=value flag. Inside the template files, these values are accessible using the \{key} syntax.

Example: If you run jbang init -t=my-template -DmyVar=hello, you can use \{myVar} within your template files to inject the value hello.

JBang uses several sources for HTTPS authentication (scripts, catalogs, and Maven repositories). The first match wins, following this order:

1. URL userinfo: Credentials in the URL (e.g., https://user:pass@host/path). Only for HTTP downloads.
2. .netrc exact host match: Per-host credentials in ~/.netrc.
3. GITHUB_TOKEN: Environment variable for github.com and related hosts.
4. GITLAB_TOKEN: Environment variable for gitlab.com and related hosts.
5. .netrc default entry: Fallback entry in ~/.netrc.
6. JBANG_AUTH_BASIC_USERNAME / JBANG_AUTH_BASIC_PASSWORD: Global fallback environment variables.

Note for Maven repositories: ~/.m2/settings.xml <server> entries are also honored and take precedence over the sources above when the server <id> matches the repository ID.