# jbx
`jbx` is the single agent-friendly entry point to the Java ecosystem: Java script running, Maven tool execution, testing, formatting, publishing, cache management, documentation, diagnostics, and JDK handling behind one CLI.
```bash
curl -fsSL https://jbx.telegraphic.dev/install.sh | bash
export PATH="$HOME/.jbx/bin:$PATH"
jbx <GAV|script.java> [args...]
```
The installer downloads a native release binary for Linux or macOS; Rust is only needed when building from source.
This repository is intentionally aiming for JBang compatibility rather than inventing a new script format.
## Current slice
Implemented now:
- `jbx run <script.java> [args...]`
- `jbx build <script.java>`
- `jbx check [path...]` checks Java source files/directories with javac `-Xlint:all` and Error Prone by default
- `jbx init <script.java>` built-in Java template generation
- `jbx template list [--json]` list built-in and imported catalog init templates
- `jbx cache clear`
- `jbx cache path [--cache-dir ...]`
- `jbx cache list [--json] [--cache-dir ...]`
- `jbx trust add|remove|list|clear` for remote script trust entries
- `jbx run --trust <http(s)://.../script.java>` / `jbx build --trust <http(s)://.../script.java>`
- `jbx app install <script.java>` install a script as a PATH command
- `jbx app uninstall <name>` remove an installed command
- `jbx app list` list installed script commands
- `jbx alias list [--json]` list aliases from the nearest `jbang-catalog.json`
- `jbx alias add <script.java|url> [args...]` add a local catalog alias
- `jbx alias remove <name>` remove a local catalog alias
- `jbx catalog add <name> <catalog-path-or-url> [--import]` register an external catalog
- `jbx catalog list [--json]` list external catalogs from the nearest `jbang-catalog.json`
- `jbx run <alias>` / `jbx <alias>` run local catalog aliases
- `jbx test [script.java|directory]` run JUnit tests with the standalone console launcher; add `--coverage` to collect JaCoCo data, generate `target/site/jacoco/index.html` plus `jacoco.xml`, and include coverage paths/counters in `--json` output (optionally pin the agent with `--jacoco-version`)
- `jbx fmt [path...]` format Java files with Palantir Java Format, including Java 25 compact scripts
- `jbx doctor [script.java|url] [--json] [--cache-dir dir] [--repo id=url] [--publish] [--native]` diagnoses JDK selection, Maven Central reachability, cache writability, formatter fallback, remote trust, dependency resolution/version drift, and context-only tools such as GPG/native-image
- `jbx rewrite patch --recipe <short|fqn> [--module <short|GAV>] [--source path] [--option key=value] [--report dir] [--json] [--fail-on-changes] [--no-fail-on-invalid-recipes] [--cache-dir dir] [--repo id=url] [--rewrite-version version]` previews OpenRewrite changes and writes `rewrite/rewrite.patch`
- `jbx rewrite apply --recipe <short|fqn> [--module <short|GAV>] [--source path] [--option key=value] [--report dir] [--json] [--fail-on-changes] [--no-fail-on-invalid-recipes] [--cache-dir dir] [--repo id=url] [--rewrite-version version]` applies OpenRewrite changes to source files
- `jbx rewrite modules [--search term] [--group groupId] [--limit n] [--json] [--rewrite-version version]` searches Maven Central for OpenRewrite modules by group and recipe/module name
- `jbx rewrite recipes <short|GAV> [--search term] [--limit n] [--detail] [--json] [--cache-dir dir] [--repo id=url] [--rewrite-version version]` lists/searches recipes available from a module; human output is a table with derived short names and FQNs, JSON includes descriptors/options
- `jbx graph dump <script.java>` print JavaParser's native AST JSON serialization
- `jbx graph import <ast.json> [-o script.java]` converts JavaParser's native AST JSON serialization back to Java source
- `jbx rewrite` runs OpenRewrite through jbx-managed dependencies and JDKs. Use `jbx rewrite patch` for previews and `jbx rewrite apply` for source mutation. Use `--recipe <short|fqn>` for recipe aliases such as `auto-format`, `format`, `cleanup`, `remove-unused-imports`, and `change-package`; use `--module <short|GAV>` for extra OpenRewrite modules (`yaml` expands to `org.openrewrite:rewrite-yaml:<version>`, full GAVs are passed through). Standard module aliases are `java`, `java-21`, `xml`, `yaml`, `properties`, `json`, `maven`, `gradle`, `groovy`, `kotlin`, `protobuf`, and `hcl`. Java recipe support is built in, Maven modules are not loaded unless requested. Recipe options use `--option key=value`; `change-package` also accepts `old=` and `new=` aliases. Use `jbx rewrite modules` to search Maven Central for `rewrite-*` modules under `org.openrewrite.recipe` and `org.openrewrite` by default; pass `--group` for other recipe groups. Use `jbx rewrite recipes <short|GAV> --detail` to search recipes and inspect short names, FQNs, descriptions, and options.
- `jbx export local <script.java|alias> [-o app.jar]` export a runnable JAR with local manifest classpath
- `jbx export portable <script.java|alias> [-o app.jar]` export a runnable JAR plus `lib/` dependencies
- `jbx export native <script.java|alias> [-o app]` export a native executable via GraalVM `native-image`
- `jbx publish [script.java] --file jbx.json --dry-run` prepares a Maven Central bundle ZIP using flat `group`/`id`/`version` metadata; `--version` overrides the descriptor version
- `jbx publish [script.java] --file jbx.json --publish` signs the artifacts, uploads the bundle through the Maven Central Portal API, and waits for publication
- `jbx publish [script.java] --file jbx.json --serve <port>` serves the prepared artifact from a local Maven-compatible HTTP repository
- `jbx install [script.java] --file jbx.json [--destination repo]` installs the artifact into a Maven repository layout; default destination is `~/.m2/repository`
- `jbx skill list [--json]` lists version-matched agent skills bundled with this jbx release, including command-specific skills such as `jbx-check`
- `jbx skill get [name]` prints a bundled agent skill; defaults to the main `jbx` skill
- `jbx docs <GAV|source|dir> [--json]` prints agent-friendly documentation; remote `group:artifact` resolves the latest release before fetching sidecars, remote GAV sidecars are cached, local sources are generated fresh
- `jbx info classpath <script.java>`
- `jbx info tools <script.java>` with `--select`
- `jbx info docs <script.java>`
- `jbx info cache [--cache-dir ...]`
- `jbx info main|java|description|gav|module <script.java>`
- `jbx info deps|repos|sources|files <script.java>`
- `jbx info compile-options|runtime-options|native-options|javaagents|manifest <script.java>`
- `jbx <GAV|script.java> [args...]` run a Java script or Maven executable tool
- `jbx --main <class> <GAV> -- [args...]` run a main class with the resolved classpath
- `jbx search [text|group:artifact[:version]] [--group G] [--id A] [--limit N] [--json]` search Maven Central artifacts
- directive parsing for:
- `//JAVA`
- `//DEPS`
- `//RUNTIME`
- `//REPOS`
- `//SOURCES`
- `//FILES`
- `//PREVIEW`
- `//JAVAC_OPTIONS` / `//COMPILE_OPTIONS`
- `//RUNTIME_OPTIONS` / `//JAVA_OPTIONS`
- `//MAIN`
- `//DESCRIPTION`
- `//GAV`
- `//MODULE`
- `//DOCS`
- `//MANIFEST`
- `//JAVAAGENT`
- `//NATIVE_OPTIONS`
- `//CDS`
- `//NOINTEGRATIONS`
- compile/run cache under the OS cache directory
- `jbx build` compiles scripts into cache without running them
- `jbx init` creates Java 25+ unnamed-class scripts from built-in or imported catalog templates (`hello`/`java`, `compact`, `cli`, `agent`, `test`, plus catalog `templates` entries), supports `--deps`, `--java`, `--template`, and `--force`
- `jbx template list` lists built-in and imported catalog init templates and supports `--json`
- `jbx cache clear` clears the compiled-script cache
- `jbx cache path` prints the effective compiled-script cache directory
- `jbx cache list` lists cached script entries with their classes/cache directories and supports `--json`
- `jbx trust add <url>` stores the current remote script content hash
- `jbx trust list`, `remove`, and `clear` manage trusted remote script entries
- remote `http://` and `https://` scripts are downloaded into cache and require matching trust before build/run unless `--trust` is passed
- remote relative `//SOURCES`, source-like `//DEPS`, and `//FILES` resources are downloaded next to the cached remote script
- remote trust hashes cover those downloaded resources
- `jbx info classpath` prints the script runtime classpath, with `--deps-only`
- `jbx info tools` prints JSON metadata for tooling and supports selecting a single field
- `jbx info docs` prints description and documentation references
- `jbx info main`, `java`, `description`, `gav`, and `module` print single metadata values
- `jbx info deps`, `repos`, `sources`, and `files` print directive collections one-per-line
- `jbx info compile-options`, `runtime-options`, `native-options`, `javaagents`, and `manifest` print advanced directive collections
- `jbx info cache` prints the effective cache directory
- `jbx doctor [script.java|url] [--json] [--cache-dir dir] [--repo id=url] [--publish] [--native]` prints human-readable environment diagnostics; `--json` emits structured checks for agents and CI, `--cache-dir` probes an isolated cache, `--repo`/`--repos` adds dependency repositories, and `--publish` / `--native` opt into contextual GPG and GraalVM `native-image` checks
- CLI overrides for `--deps`, `--repo`, `--source`, `--files`, `--java`, `--main`, `--compile-option`, `--java-option`, and `--javaagent`
- local and imported catalog aliases from `jbang-catalog.json` / `.jbang/jbang-catalog.json`, including `alias add/remove`, `catalog add/list`, `base-ref`, `script-ref`, `catalog-ref`, `import`, `arguments`, `dependencies`, `repositories`, `sources`, `files`, classpaths, Java/runtime/compile options, agents, Java version, and main-class metadata
- imported catalog templates with `file-refs` and default `properties`, usable via `jbx init --template <name>`
- `jbx export local` creates runnable JARs whose manifest classpath points at local dependency paths
- `jbx export portable` creates runnable JARs and copies file-based dependency classpath entries into sibling `lib/`
- `jbx export native` compiles scripts then invokes GraalVM `native-image`, passing `//NATIVE_OPTIONS` plus `--native-option` values
- `jbx publish --dry-run` reads `jbx.json` by default, accepts flat `group` / `id` / `version` metadata, supports `--version` overrides, compiles/stages all declared Java sources including compact unnamed-class scripts, and writes a Maven repository-layout Central bundle with main, sources, generated javadoc when possible, POM, `-jbx-docs.md` / `-jbx-docs.json` sidecars, and required checksum artifacts
- `jbx publish --publish` uploads the signed Central bundle to the Portal API with `publishingType=AUTOMATIC` by default and polls `/api/v1/publisher/status` until it is `PUBLISHED` or `FAILED`
- `jbx publish --serve <port>` prepares the same Maven repository layout unsigned and serves it from `http://127.0.0.1:<port>/`; port `0` asks the OS to choose a free port; it also serves artifact-level `maven-metadata.xml` plus checksums so version-less Maven lookups work
- `jbx install` installs the current project into `~/.m2/repository` by default or another Maven-layout repository with `--destination` / `--to`; it updates `maven-metadata-local.xml` for the installed artifact
- `jbx skill list [--json]` and `jbx skill get [name]` expose version-matched agent guidance bundled with the binary. The main skill and command skills are rendered from website command Markdown in `website/content/pages/docs/commands/`; derived static copies live in `skill-data/` and installable `skills/`, with command skills named `jbx-<command>`.
- `jbx docs <source|dir>` generates Markdown docs from local Java sources without writing cache entries
- `jbx docs <group:artifact>` resolves the latest Maven release metadata before fetching `artifact-version-jbx-docs.md`
- `jbx docs <group:artifact:version> [--json]` fetches `artifact-version-jbx-docs.md` or `.json` Maven sidecars and caches remote results under the docs cache namespace; see [`docs/jbx-docs-schema.md`](docs/jbx-docs-schema.md) for the JSON shape
- `jbx graph dump <script.java>` emits JavaParser's native JSON serialization directly; there is no jbx-specific graph text or custom JSON shape
- `jbx graph import <ast.json>` deserializes JavaParser JSON and prints JavaParser-formatted Java source to stdout; pass `-o <script.java>` / `--output <script.java>` to write a file
- Java 25 compact source files and `import module` declarations are parsed directly by JavaParser 3.28.1+
- Java package-aware main-class inference
- `//FILES` resources copied onto the runtime classpath
- non-coordinate `//DEPS` treated as source dependencies; Maven coordinates may be `group:artifact:version`, `group:artifact:classifier:version`, or just `group:artifact` to resolve the latest release from Maven metadata
- `//PREVIEW` compile/runtime flag handling
- `jbx resolve <coordinates...>` resolve Maven coordinates to dependency list
- `jbx resolve --classpath <coordinates...>` resolve to classpath
- `jbx fetch <coordinates...>` fetch artifacts and print classpath
- `jbx fetch --deps-only <coordinates...>` print coordinates instead of paths
- `jbx search <text|group:artifact[:version]>` queries Maven Central Search; `--group`, `--id`/`--artifact-id`, and `--version` add Solr field filters (`g`, `a`, `v`); default text output is an aligned table sorted by version-count popularity, and `--json` returns structured `query`, `numFound`, and `artifacts` for agents
- `jbx jdk list` list discovered/cached JDKs
- `jbx jdk home [version]` print the JDK home for a version (default: 25)
- `jbx jdk install <version>` download a Temurin JDK from Adoptium
- native Maven dependency resolver (no Coursier required)
- reuses existing Maven (`~/.m2/repository`), Gradle (`~/.gradle/caches`), and Coursier (`~/.cache/coursier`) caches via symlinks
- discovers existing JDKs from `JAVA_HOME`, `PATH`, JBang (`~/.jbang/jdks`), SDKMAN (`~/.sdkman/candidates/java`), mise (`~/.local/share/mise/installs`), Gradle (`~/.gradle/jdks`), and system JVM directories
- caches discovered JDKs under `~/.cache/jbx/jdks/<major>` via symlinks so future runs do not rescan everything
- auto-provisions missing JDKs from Adoptium/Eclipse Temurin with SHA-256 archive verification
Not yet implemented: catalog remove for nested catalogs, multi-file template expansion, template property CLI overrides, export mavenrepo/jlink/project variants, edit integration, and the rest of JBang's lovely edge-case museum.
## Example
```java
//JAVA 25+
void main(String[] args) {
IO.println("hello " + args[0]);
}
```
```bash
jbx check
# checks all Java files under the current directory with javac -Xlint:all and Error Prone
jbx check src --no-error-prone --json
# structured javac diagnostics only
```
```bash
jbx run Hello.java world
# hello world
jbx dev.telegraphic:hello-tool:1.0.0 -- --help
# runs an executable JAR from Maven coordinates
```
### `jbx.json` publish descriptor
```json
{
"main": "src/main/java/dev/telegraphic/demo/HelloTool.java",
"group": "dev.telegraphic.demo",
"id": "hello-tool",
"version": "1.0.0",
"package": "dev.telegraphic.demo",
"description": "Small demo tool",
"url": "https://github.com/telegraphic-dev/hello-tool",
"licenses": [
{
"name": "MIT License",
"url": "https://opensource.org/licenses/MIT"
}
],
"developers": [
{
"name": "Telegraphic",
"organizationUrl": "https://github.com/telegraphic-dev"
}
],
"scm": {
"connection": "scm:git:https://github.com/telegraphic-dev/hello-tool.git",
"developerConnection": "scm:git:ssh://git@github.com/telegraphic-dev/hello-tool.git",
"url": "https://github.com/telegraphic-dev/hello-tool"
},
"java": "25",
"dependencies": [
"info.picocli:picocli:4.7.7"
],
"runtimeDependencies": [
"org.slf4j:slf4j-nop:2.0.17"
],
"repositories": [
"https://repo.maven.apache.org/maven2"
]
}
```
```bash
jbx publish --file jbx.json --dry-run --gpg-key you@example.com
jbx publish --file jbx.json --version 1.0.1 --dry-run --gpg-key you@example.com
jbx publish --file jbx.json --dry-run --skip-signing # local inspection only
CENTRAL_TOKEN_USERNAME=... CENTRAL_TOKEN_PASSWORD=... jbx publish --file jbx.json --publish --gpg-key you@example.com
# or set CENTRAL_PORTAL_TOKEN to base64(username:password)
```
Use `--version` when release/tag workflows need to publish a different version than the descriptor. The `main` field accepts either a source path (`src/main/java/dev/telegraphic/demo/HelloTool.java`) or a Java FQN (`dev.telegraphic.demo.HelloTool`). If `main` has no extension, `jbx publish` first checks the exact path, then tries `.java`, `.jsh`, and `.jav` next to the descriptor, then scans Java sources under the descriptor directory for a matching package/class declaration; missing main files get an explicit `publish main source not found` error.
Use `dependencies` / `//DEPS` for dependencies needed to compile the published artifact. Use `runtimeDependencies` / `//RUNTIME` for runtime-only implementations that should appear in generated Maven metadata with `runtime` scope without being required on the compile classpath.
For GitHub-hosted repositories, `jbx publish` can prefill Maven Central POM `url`, `licenses`, `developers`, and `scm` metadata from the `origin` remote plus `gh repo view` when those fields are omitted. Put the fields in `jbx.json` when you want explicit release metadata instead of GitHub-derived defaults. Signed Central-ready bundles require a configured GPG key; `--skip-signing` is only for local inspection. Real Portal publishing requires a generated Maven Central user token supplied via environment variables only: preferably `CENTRAL_TOKEN_USERNAME` / `CENTRAL_TOKEN_PASSWORD`, or `CENTRAL_PORTAL_TOKEN` containing the base64-encoded `username:password` value expected by the Portal API.
A real multi-artifact release setup looks like `telegraphic-dev/jbx-utils`: each helper (`jbx-check`, `jbx-graph`, `jbx-rewrite`) has its own `jbx.json`, PR CI runs a script around `jbx publish --dry-run --skip-signing`, and the release workflow publishes with a matrix only after a GitHub release or manual dispatch. The publish workflow imports `GPG_PRIVATE_KEY`/`GPG_PASSPHRASE`, sets `CENTRAL_TOKEN_USERNAME`/`CENTRAL_TOKEN_PASSWORD`, derives the version from `workflow_dispatch` input or `GITHUB_REF_NAME#v`, then runs:
```bash
jbx publish \
--publish \
--file "${PROJECT}/jbx.json" \
--version "$VERSION" \
--output "target/${PROJECT}-central-bundle.zip" \
--target-dir "target/publish/${PROJECT}" \
--cache-dir .jbx-cache
```
Keep `--publish` out of PR CI. Normal checks should prove the bundle shape; the release workflow should be the only place that talks to Maven Central.
Full descriptor and GitHub Actions examples are in `docs/jbx-json.md` and `/docs/jbx-json/` on the website.
## Development
```bash
cargo test --locked
cargo fmt --check
```