# jbx
`jbx` is a Rust-native Java toolbox: JBang-compatible script running, Maven tool execution, testing, formatting, publishing, cache management, and JDK handling behind one CLI.
```bash
jbx <GAV|script.java> [args...]
```
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
- `jbx fmt [path...]` format Java files with Palantir Java Format, including Java 25 compact scripts
- `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 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
- directive parsing for:
- `//JAVA`
- `//DEPS`
- `//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`, 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
- 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, 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`
- Java package-aware main-class inference
- `//FILES` resources copied onto the runtime classpath
- non-coordinate `//DEPS` treated as source dependencies
- `//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 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"
],
"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. If `main` has no extension, `jbx publish` first checks the exact path and then tries `.java`, `.jsh`, and `.jav` next to the descriptor; missing main files get an explicit `publish main source not found` error.
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.
## Development
```bash
cargo test --locked
cargo fmt --check
```