Getting Started

This guide covers the shortest path from clone or download to a working Quarkus Forge setup. For deployment and adoption considerations, see Security.

Requirements

  • Java 25

  • Maven 3.9+

Build

Full build (TUI + headless)

mvn -q -DskipTests package
# or: just build
# or: ./mvnw -DskipTests package

This creates target/quarkus-forge.jar.

Headless-only build

mvn -q clean package -Pheadless
# or: just build-headless
# or: ./mvnw clean package -Pheadless

This creates target/quarkus-forge-headless.jar — a smaller jar without TUI/terminal dependencies, ideal for CI pipelines and containers.

A justfile is included with common recipes. Run just to see all available commands. A Maven Wrapper (./mvnw) is also included — no global Maven install required.

Choose Your Mode

Goal Use Why

Interactive exploration

quarkus-forge.jar

Includes the full TUI

CI / container automation

quarkus-forge-headless.jar

Smaller and avoids TUI dependencies

One local developer artifact

quarkus-forge.jar

Supports both TUI and generate

Smallest runtime footprint

native binary

No JVM required at runtime (build separately with GraalVM Native Image prerequisites)

GitHub releases use quarkus-forge-jvm.jar for the interactive JVM asset and publish a matching .sha256 file for every jar and native download.

Checksum verification examples for Linux, macOS, and Windows are collected in Release Checksums.

TUI mode (interactive):

java --enable-native-access=ALL-UNNAMED -jar target/quarkus-forge.jar
--enable-native-access=ALL-UNNAMED suppresses Panama FFM warnings from the TamboUI terminal backend.

Headless mode (automation/CI):

java -jar target/quarkus-forge-headless.jar generate \
  --group-id org.acme \
  --artifact-id demo \
  --build-tool maven \
  --java-version 25 \
  --preset web \
  --extension io.quarkus:quarkus-smallrye-health
The full jar (quarkus-forge.jar) also supports the generate subcommand. The headless-only jar is preferred for CI/containers as it carries no TUI or terminal dependencies.

Deterministic replay with a Forgefile:

java -jar target/quarkus-forge-headless.jar generate --from Forgefile

Save a reusable template in the machine-local recipes library:

java -jar target/quarkus-forge-headless.jar generate \
  --dry-run \
  --group-id org.acme \
  --artifact-id demo \
  --build-tool maven \
  --java-version 25 \
  --save-as starter.json

Install With JBang

Run directly from the org catalog:

jbang quarkus-forge@ayagmar

Run the headless-only version (no TUI dependencies):

jbang quarkus-forge-headless@ayagmar generate \
  --group-id org.acme \
  --artifact-id demo

Install as a local command:

jbang app install --name quarkus-forge quarkus-forge@ayagmar
quarkus-forge

Bash Completion

Generate completion scripts after building the jars:

just completion-bash

This writes:

  • target/completions/quarkus-forge.bash

  • target/completions/quarkus-forge-headless.bash

Load them into the current shell:

source target/completions/quarkus-forge.bash
source target/completions/quarkus-forge-headless.bash

Release Checksums

GitHub releases publish a matching .sha256 file for each JVM jar and native binary.

Verify a downloaded release artifact

Linux:   sha256sum -c <artifact>.sha256
macOS:   shasum -a 256 -c <artifact>.sha256

Examples:

sha256sum -c quarkus-forge-jvm.jar.sha256
sha256sum -c quarkus-forge-headless-linux-x86_64.sha256

For Windows downloads, use the PowerShell example below.

$expected = (Get-Content .\quarkus-forge-headless-windows-x86_64.exe.sha256).Split(' ')[0].ToLower()
$actual = (Get-FileHash .\quarkus-forge-headless-windows-x86_64.exe -Algorithm SHA256).Hash.ToLower()
if ($actual -eq $expected) {
  Write-Host "Checksum verified"
  exit 0
} else {
  Write-Error "Checksum mismatch"
  exit 1
}

Generate checksums for locally built jars

For locally built release jars in target/:

Generate .sha256 files:

just release-checksums

Verify locally built artifacts:

sha256sum -c target/quarkus-forge.jar.sha256
sha256sum -c target/quarkus-forge-headless.jar.sha256

Next Steps