Getting Started

Obtaining the Tool

The tool is a single jar that you can run in four ways:

All four ways use the same advisors and the same settings.

Start with the Web UI

Go to the root of your project and start the settings page. It runs on your machine only.

 
mvn fish.payara.tools:payara-platform-migration-tool:<version>:start

Your browser opens a page where you choose:

Click Start to see live progress. The page also shows the command it runs, which you can copy to use in scripts or CI.

Analyze Your Project (No AI)

Go to the root of your project and run:

 
mvn fish.payara.tools:payara-platform-migration-tool:<version>:migrate \
  -Dmigration.dir=. \
  -Dmigration.advisor=true

This runs the advisors, applies the automatic fixes (recipes) and writes a report. To only report what would change without editing any file, add -Dmigration.apply=false. To only detect which technologies your project uses, use -Dmigration.detection=true.

Upgrade Your Project with the AI Agent

By default, the tool upgrades to Jakarta EE 11. To upgrade to Jakarta EE 10, add -Dmigration.target=10.

Using the jar without Maven

The jar has the same commands as the Maven goals: start, migrate, view and help. Settings are passed as --migration.<name>=<value> instead of -Dmigration.<name>=<value>. A command is always required.

 
java -jar payara-platform-migration-tool-<version>.jar migrate \
  --migration.dir=/path/to/your-app \
  --migration.advisor=true

The AI provider settings are not migration.* settings. With the jar, set them as environment variables, or as -D properties placed before -jar.

Supported Providers

These variables configure the provider. With Maven, set them as environment variables or as -D flags.

For guidance on which provider and model to use, see Choosing an LLM.

Interactive Mode

To review each file change before it is written, enable interactive mode. The tool asks for a yes or no in the terminal before the agent writes a file. This needs an interactive terminal.

 
mvn fish.payara.tools:payara-platform-migration-tool:<version>:migrate \
  -Dmigration.advisor=true -Dmigration.agent=true \
  -Dmigration.agent.interactive=true

Using the Tool from Claude Code

The jar can also run as an MCP server. Claude Code can then ask the tool what your project needs, run the automatic recipes, apply the recommended fixes with its own tools, and check that the project still builds. No AI provider settings are needed, because Claude Code does the AI work.

Go to your project and add the server:

 
cd /path/to/your-app
claude mcp add payara-platform-migration-tool -- java -jar /path/to/payara-platform-migration-tool-<version>.jar mcp

To add it for every project, add --scope user. To let it work only inside certain folders, add --allowed-roots=/path/one,/path/two after mcp.

Start Claude Code after adding the server, and type /mcp to check that it shows as connected. A session that is already running does not pick up a new server.

Then ask Claude Code, in this order:

Claude Code asks your permission before it calls the tools that change files (run_recipes, apply_guided_recipes) or run your build (compile, test). The server does not make git commits, so commit or branch first and review the result with git diff.

Gradle and Other Projects

The tool compiles your project with its own build tool: Maven (using mvnw if present), Gradle or Ant. Run it as the jar, which does not need a pom.xml. Dependency changes are written for Maven pom.xml files only. For Gradle projects, source and descriptor findings are handled, but dependency changes are partly manual.

For Gradle and Ant projects, use the standalone jar command:

 
java -jar payara-platform-migration-tool-<version>.jar migrate \
  --migration.dir=/path/to/your-app \
  --migration.advisor=true

Stopping a Run

Use the Stop button on the live report page. The run ends at the next safe point, never in the middle of an edit, and every change made so far stays on disk. The report is written and marked STOPPED. A stop is not a failed build: the Maven goal ends with a warning and the jar exits with code 130.

Parameter Reference

The same migration.* settings work in both forms. Maven takes them as -Dmigration.dir=…​, the jar as --migration.dir=…​. A jar flag without a value means true. Run the help goal (or java -jar …​ help) to print the same list from the tool.