Quick Start Guide

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

Step 0: Prerequisites

Windows (UTF-8)

Modern Linux distributions and MacOS terminal environments are configured to use UTF-8 as the default character encoding for the console, allowing them to handle a vast array of international characters and symbols seamlessly. In contrast, Windows environments have historically relied on legacy, region-specific code pages (such as CP437 or Windows-1252) for both the Command Prompt (CMD) and Windows PowerShell. Consequently, Windows users often encounter encoding issues when displaying special characters unless they manually configure their shell settings to explicitly support UTF-8.

Test.java
public class Test {
    public static void main(String[] args) {
        String heart = "\u2764";
        System.out.println("I " + heart + "  JBang!");
    }
}

To check if UTF-8 support is enabled on Windows, run program Test.java using command:

  • C:\> java Test.java

from CMD or PowerShell. If UTF-8 support is enabled, the following text will be displayed

  • I ❤ JBang!

otherwise the text will appear as

  • I ? JBang!

UTF-8 support can be temporarily enabled for CMD, PowerShell, or Bash with command: chcp.com 65001. To permanently enable UTF-8 support:

  • CMD - add the following registry key:

    reg add "HKLM\Software\Microsoft\Command Processor" /v "Autorun" /t REG_SZ /d "@chcp 65001>nul" /f

  • PowerShell - add the following line to the file specified by $PROFILE

    $OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)

  • Bash (Git-Bash or Cygwin) - add the following line to ~/.bashrc

    chcp.com 65001 > /dev/null

Alternatively, UTF-8 can be enabled globally on Windows for all programs and shells by opening the intl.cpl control panel applet and enabling option:

  • [ ] Beta: Use Unicode UTF-8 for worldwide language support

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! 🚀