Running and Publishing JBang Apps from Catalogs

Distributing command-line Java applications traditionally involved building shadow JAR files, packaging ZIP archives, or writing operating system installers. JBang Catalogs revolutionize Java application distribution by allowing developers to turn any GitHub repository, Gist, or HTTP server into an instant, zero-configuration software catalog.

1. What is a JBang Catalog?

A JBang Catalog is a lightweight JSON manifest (named jbang-catalog.json) that maps short, friendly app names (aliases) to raw Java source files, URLs, or Maven coordinates. It allows anyone on any machine with JBang installed to run your Java software with a single short command.

2. Running Apps Directly from Remote Catalogs

You can execute public JBang applications instantly without manually downloading files or configuring classpath parameters.

Syntax:

$ jbang alias@github-user/repository-name [arguments]

Example: Running Official JBang Examples

# Run the 'helloworld' alias from the 'jbangdev/jbang-examples' repository
$ jbang helloworld@jbangdev/jbang-examples

# Output:
# Hello World from JBang!

JBang transparently handles fetching the script, downloading the necessary Java runtime (e.g. Java 21) if missing, resolving Maven dependencies, and executing the application.

3. Installing Applications Globally (`jbang app install`)

If you use a JBang utility frequently, you can install it as a native command-line application on your operating system. JBang creates a wrapper script in your PATH so you can execute the command directly without prefixing it with jbang.

# Install an app globally from a GitHub catalog
$ jbang app install helloworld@jbangdev/jbang-examples

# Now run it directly as a native system command from any directory!
$ helloworld

To list or uninstall globally managed JBang applications:

# List all installed JBang applications
$ jbang app list

# Uninstall an application
$ jbang app uninstall helloworld

4. How to Create and Publish Your Own JBang Catalog

Publishing your own Java tools as a catalog is remarkably simple and requires no specialized build infrastructure.

Step 1: Write Your Java Script

Create your Java application file (e.g., SysInfo.java) using standard JBang directives:

///usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 21
//DEPS info.picocli:picocli:4.7.6

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

@Command(name = "sysinfo", description = "Displays System Diagnostics")
public class SysInfo implements Runnable {

    public static void main(String... args) {
        new CommandLine(new SysInfo()).execute(args);
    }

    @Override
    public void run() {
        System.out.println("OS: " + System.getProperty("os.name"));
        System.out.println("Java Version: " + System.getProperty("java.version"));
        System.out.println("Available Processors: " + Runtime.getRuntime().availableProcessors());
    }
}

Step 2: Generate the `jbang-catalog.json` File

In the root folder of your project repository, create an alias for your script using the JBang CLI:

$ jbang alias add --name=sysinfo --description="Displays System Diagnostics" SysInfo.java

This automatically generates or updates a jbang-catalog.json file in your folder:

{
  "catalogs": {},
  "aliases": {
    "sysinfo": {
      "script-ref": "SysInfo.java",
      "description": "Displays System Diagnostics"
    }
  }
}

Step 3: Push to GitHub & Share

Commit both SysInfo.java and jbang-catalog.json to your GitHub repository (e.g., https://github.com/myusername/my-tools). Anyone in the world can now run your tool immediately:

$ jbang sysinfo@myusername/my-tools

5. Catalog & App Management Command Reference

Frequently Asked Questions (FAQs)

Q1: Can I publish private JBang catalogs for internal company use?

Yes. If your GitHub repository is private or hosted on an internal GitHub Enterprise / GitLab server, JBang uses your local SSH keys or git credentials to access and execute private catalogs securely.

Q2: How do users receive updates when I publish a new version of my script?

By default, JBang checks for catalog updates periodically. Users can force JBang to fetch the latest version of a remote script or catalog immediately by passing the --fresh flag: jbang --fresh sysinfo@user/repo.

Q3: What happens if a user doesn't have the required Java version installed?

JBang reads the //JAVA directive inside your script (e.g., //JAVA 21) and automatically downloads a portable JDK runtime transparently if the user's host environment lacks a compatible JVM.

Conclusion

JBang Catalogs eliminate the historical friction of building, packaging, and distributing Java software. By leveraging GitHub repositories as software catalogs, you can deliver instant, cross-platform Java CLI applications to users worldwide with zero build configuration.