# `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

```bash
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

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

### Generate OpenAPI from the specification file

```bash
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

```bash
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`

```text
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:

```bash
jbx skill get jbx-run
```