jbx toolbox logojbx

run

Compile and run one Java source file or launch a Maven executable artifact, including Java 25 compact scripts, with JBang-style directives and CLI overrides.

When to use it

  • Run a self-contained Java script without creating a Maven or Gradle project.
  • Launch a compact script that carries //DEPS, //JAVA, //SOURCES, and runtime options in the file.
  • Launch an executable Maven artifact from coordinates such as group:artifact:version.
  • Smoke-test an executable example after jbx check --json has confirmed the source compiles.

Common workflows

jbx run report.java --month 2026-05
jbx run com.example:report-cli --month 2026-05
jbx run --progress always com.example:report-cli --month 2026-05

Passing arguments

run options go before the script path or Maven coordinate. After the target, arguments belong to the Java program, including Picocli-style options such as --help, --input, or --verbose.

Use an explicit -- only when the Java program needs to receive a literal double-dash argument.

Progress and stdout cleanliness

Program stdout belongs to the Java program. jbx lifecycle messages for dependency resolution, JVM preparation, and launch phases are written to stderr so commands like jbx run app.java > result.json do not corrupt stdout.

Use --progress auto|always|never to control lifecycle messages. Auto mode emits human feedback only when stderr is interactive; --progress always is useful for debugging cold cache downloads; --quiet suppresses jbx lifecycle messages.

Real-life examples

Start NanoCode Agent

gh repo clone glaforge/nanocode
cd nanocode
export GOOGLE_AI_GEMINI_API_KEY="***"
jbx nanocode_basic.java

Generate OpenAPI from the specification file

jbx org.openapitools:openapi-generator-cli generate \
  -i openapi.yaml \
  -g java \
  -o generated/petstore-client \
  --api-package com.example.petstore.api \
  --model-package com.example.petstore.model \
  --invoker-package com.example.petstore.client

Start H2 In-Memory Database

jbx com.h2database:h2

Agent loop

  1. Inspect the target with jbx info directives <script> or jbx search <artifact> --json.
  2. Preflight source with jbx check --json or jbx build when execution has side effects.
  3. Run with program arguments after the script/artifact target, without adding -- unless the program needs a literal double dash.
  4. Verify outputs, generated files, or service readiness directly.

Agent notes

run executes arbitrary user code. Prefer info, build, check --json, or doctor --json first when the command source, dependencies, or environment are not understood.

Verification checklist

  • The target script or artifact coordinate is the intended one.
  • Source targets compile before execution when safety matters.
  • Program arguments are passed after the target and are visible to the Java program.
  • Generated files, network listeners, or exit codes are checked with a second command.

Arguments and flags

This section is copied from the CLI help for this release so the page explains the actual accepted arguments.

jbx run

Run Java source or Maven artifact

Usage: jbx run [OPTIONS] <SCRIPT> [ARGS]...

Arguments:
  <SCRIPT>   Java source file or Maven coordinates to launch
  [ARGS]...  Arguments passed to the script/tool

Options:
      --deps <DEPS>                       Additional dependency coordinates, same shape as //DEPS
      --repo <REPOS>                      Additional repository, same shape as //REPOS
      --source <SOURCES>                  Additional source file, same shape as //SOURCES
      --files <FILES>                     Additional file/resource, same shape as //FILES
      --class-path <CLASSPATH>            Additional classpath entries
      --javac-option <JAVAC_OPTIONS>      Additional javac option
      --runtime-option <RUNTIME_OPTIONS>  Additional java runtime option
      --java <JAVA_VERSION>               Override //JAVA requested version
      --javaagent <JAVA_AGENTS>           Additional java agent, same shape as //JAVAAGENT
      --main <MAIN_CLASS>                 Override //MAIN / inferred class name
      --cache-dir <CACHE_DIR>             Override cache directory
      --trust                             Trust this remote script content hash before running
  -q, --quiet                             Suppress jbx lifecycle/progress messages; program stdout/stderr still pass through
  -v, --verbose                           Show jbx lifecycle/progress messages even when auto mode would stay quiet
      --progress <PROGRESS>               Control jbx lifecycle/progress messages. Progress is written to stderr [default: auto] [possible values: auto, always, never]
  -h, --help                              Print help

Skill

Agents can fetch the matching versioned skill with:

jbx skill get jbx-run