Quick Start Guide

This guide will get you up and running with JBang in just a few minutes!

Step 1: Install JBang

Choose your preferred installation method:

Linux/macOS/Windows (WSL/Git Bash):

curl -Ls https://sh.jbang.dev | bash -s - app setup

Windows PowerShell:

iex "& { $(iwr -useb https://ps.jbang.dev) } app setup"

Option 2: Package Managers

SDKMan (Linux/macOS):

sdk install jbang

Homebrew (macOS):

brew install jbangdev/tap/jbang

Chocolatey (Windows):

choco install jbang

Scoop (Windows):

scoop bucket add jbangdev https://github.com/jbangdev/scoop-bucket
scoop install jbang

Verify Installation

jbang --version

Step 2: Your First Script

Create a simple "Hello World" script:

jbang init hello.java

This creates:

///usr/bin/env jbang "$0" "$@" ; exit $?

import static java.lang.System.*;

public class hello {
  public static void main(String... args) {
    out.println("Hello World");
  }
}

Run it:

jbang hello.java
# Output: Hello World!

Step 3: Add Dependencies

Let’s create a more interesting script with external dependencies:

jbang init --template=cli weather.java

Edit the file to add weather functionality:

///usr/bin/env jbang "$0" "$@" ; exit $?

//DEPS info.picocli:picocli:4.7.7
//DEPS com.fasterxml.jackson.core:jackson-core:2.20.0
//DEPS com.fasterxml.jackson.core:jackson-databind:2.20.0

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Parameters;

@Command(name = "weather", mixinStandardHelpOptions = true, description = "Get weather information for a city")
class weather implements Runnable {

  @Parameters(index = "0", description = "City name")
  private String city;

  public static void main(String[] args) {
    new CommandLine(new weather()).execute(args);
  }

  @Override
  public void run() {
    try {
      String url = "https://wttr.in/" + city + "?format=j1";
      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder().uri(URI.create(url)).build();

      HttpResponse<String> response = client.send(request,
          HttpResponse.BodyHandlers.ofString());

      // Simple output - in real app you'd parse the JSON
      System.out.println("Weather for " + city + ":");
      System.out.println("Raw data: " + response.body().substring(0, 200) + "...");
    } catch (Exception e) {
      System.err.println("Error fetching weather: " + e.getMessage());
    }
  }
}

Run it:

jbang weather.java London

Step 4: IDE Integration

Get full IDE support for your script:

jbang edit weather.java

This will:

  • Install VSCodium (if not present)

  • Generate a project structure

  • Open the script in the IDE with full IntelliSense

Step 5: Explore Templates

See what templates are available:

jbang template list

Try different templates:

# Create a CLI app
jbang init --template=cli myapp.java

# Create a web server
jbang init --template=qcli webapp.java

# Create a JavaFX app
jbang init --template=javafx gui.java

Step 6: Share Your Scripts

Create an Alias

jbang alias add --name weather weather.java

Now you can run:

jbang weather London

Share via GitHub

  1. Push your script to GitHub

  2. Others can run it directly:

jbang https://github.com/yourusername/yourrepo/blob/main/weather.java London

Common Next Steps

Export to Traditional Project

# Export to Maven project
jbang export maven weather.java

# Export to Gradle project
jbang export gradle weather.java

Create Native Binary

# Requires GraalVM native-image
jbang --native weather.java

Install as System Command

jbang app install weather.java
weather London  # Now available as system command

Helpful Commands

# List all JBang commands
jbang --help

# Get help for specific command
jbang init --help

# Check for updates
jbang version

# Clear cache
jbang cache clear

What’s Next?

Troubleshooting

Java not found? JBang will automatically download Java if needed. Set JBANG_DEFAULT_JAVA_VERSION to control the version:

export JBANG_DEFAULT_JAVA_VERSION=17

Permission denied on scripts? Make them executable:

chmod +x yourscript.java

Need offline mode?

jbang --offline yourscript.java

Happy scripting! 🚀