Getting started

jbx accepts either a Java script path or a Maven coordinate.

Install it:

curl -fsSL https://jbx.telegraphic.dev/install.sh | bash
export PATH="$HOME/.jbx/bin:$PATH"

The installer downloads a native Linux or macOS binary. Source builds are only needed when contributing to jbx itself.

jbx run Hello.java world
jbx build Hello.java
jbx check src --json
jbx fmt src
jbx doctor --json
jbx rewrite patch --recipe auto-format --source src/main/java --json
jbx test
jbx test --coverage   # writes target/site/jacoco/index.html and jacoco.xml
jbx test --coverage --json
jbx test --coverage --jacoco-version 0.8.13
jbx skill get

Java scripts

Java 25 compact scripts are the default target. A minimal script can be as small as this:

void main(String[] args) {
  IO.println("hello " + args[0]);
}

Run it:

jbx Hello.java world

Diagnostics

Use jbx doctor when a script, cache, toolchain, or dependency resolution path behaves oddly:

jbx doctor
jbx doctor --json
jbx doctor Hello.java --json
jbx doctor https://example.com/Hello.java --cache-dir .jbx-cache --repo snapshots=https://repo.example.test/maven --publish --native

The command checks the selected JDK, Maven Central reachability, cache writability, formatter availability and fallback, remote script trust, dependency resolution health, dependency version drift, and whether a newer jbx release exists. GPG and GraalVM native-image are contextual: they are skipped by default and checked when --publish or --native asks for them.

Executable artifacts

Executable Maven artifacts can be invoked directly:

jbx dev.telegraphic:hello-tool:1.0.0 --help

Use --main when an artifact exposes more than one entry point. For the full publish-and-run path, see the end-to-end executable artifact guide.

OpenRewrite recipes

jbx rewrite runs OpenRewrite recipes through jbx-managed dependencies and JDKs. Start with a patch preview:

jbx rewrite patch --recipe auto-format --source src/main/java
jbx rewrite patch --module yaml --recipe org.openrewrite.yaml.format.AutoFormat --source config
jbx rewrite patch --recipe change-package --option old=com.old --option new=com.new --source src --report rewrite --json

Inspect rewrite/rewrite.patch, then apply when the change is wanted:

jbx rewrite apply --recipe cleanup --source src/main/java

For CI-style checks, add --fail-on-changes. For custom recipe modules, add --repo id=url, --cache-dir dir, or --rewrite-version version when you need a specific repository, isolated cache, or OpenRewrite release.

Discovery commands are machine-readable for agents:

jbx rewrite modules --search yaml --group org.openrewrite --rewrite-version 8.60.0 --json
jbx rewrite recipes yaml --search format --detail --json

Publishing metadata

jbx publish --file jbx.json --dry-run stages Maven-ready artifacts before any real release. Keep the descriptor lean: use dependencies (or //DEPS in a script) for libraries needed to compile the artifact, and runtimeDependencies (or //RUNTIME) for runtime-only libraries such as logging backends or recipe helper providers. See the jbx.json descriptor reference for the full field list and schema.

{
  "main": "HelloTool.java",
  "group": "dev.telegraphic.demo",
  "id": "hello-tool",
  "version": "1.0.0",
  "dependencies": ["info.picocli:picocli:4.7.7"],
  "runtimeDependencies": ["org.slf4j:slf4j-nop:2.0.17"]
}

Runtime dependencies are emitted to Maven metadata with runtime scope and are not required on the compile classpath.

Documentation sidecars

jbx docs can read local sources or fetch published Markdown/JSON sidecars from Maven repositories:

jbx docs src/main/java
jbx docs com.fasterxml.jackson.core:jackson-databind
jbx docs com.fasterxml.jackson.core:jackson-databind --json