Skip to main content

Deploy the Moderne CLI from an internal Maven Central mirror

This guide walks through installing and configuring the Moderne CLI in environments where the CLI must fetch its distribution and recipe artifacts from an internal artifact repository instead of accessing the public internet directly.

By the end of this guide, you'll have the CLI installed from your internal mirror and stocked with the recipe JARs needed to run recipes.

Prerequisites​

This guide assumes that you have:

  • An internal artifact repository mirroring Maven Central (e.g., Artifactory or Nexus)
  • A Moderne license - which you'll activate per the Moderne CLI license documentation after completing the installation of the CLI

Step 1: Ensure required artifacts exist in your internal artifact repository​

Before installing the CLI, ensure your internal artifact repository contains the following artifacts:

  • The Moderne CLI distribution — distributed as a platform-specific self-extracting installer that bundles the modw wrapper, a Java 25 runtime, and the CLI JAR. It's published to Maven Central under platform-specific artifact IDs: moderne-cli-linux, moderne-cli-osx, and moderne-cli-windows.
  • Recipe modules — see the latest versions of every OpenRewrite module reference for the full list of recipe JARs and a ready-to-run CLI install command. The reference covers both the open-source OpenRewrite recipes (org.openrewrite.*) and Moderne's proprietary recipes (io.moderne.recipe).

If your mirror is configured as a remote proxy of Maven Central (e.g., a virtual repository in Artifactory or a proxy repo in Nexus), artifacts are fetched on demand and cached automatically. If your mirror requires explicit sync-on-approval, each version you intend to use must be synced before users can install or upgrade.

Step 2: Install the CLI from your internal mirror​

The CLI ships as a platform-specific installer that bundles the modw wrapper, a Java 25 runtime, and the CLI JAR. On Linux/macOS it's a self-extracting shell script (.sh). On Windows it's a zip archive (.zip) containing an install.cmd to run after extracting. Either way, installation drops everything into ~/.moderne/cli/ (or %USERPROFILE%\.moderne\cli on Windows) without further network access.

Download the platform-appropriate distribution from your internal mirror. For example, for Linux x86_64:

curl -fL -o moderne-cli.sh \
    "https://internal-mirror.example.com/io/moderne/moderne-cli-linux/4.2.10/moderne-cli-linux-4.3.4.sh"

Replace the version with the one you intend to install, and adjust the artifact name to match your platform (moderne-cli-linux or moderne-cli-osx).

Then run the installer:

bash moderne-cli.sh

The installer adds ~/.moderne/cli/bin to your PATH and configures shell completion. Open a new terminal (or source your shell's rc file) to pick up the changes.

The macOS distribution bundles a JRE for Apple Silicon only. Intel Mac users will need to install a Java 25+ runtime separately and ensure it's discoverable by the wrapper — see how the wrapper finds Java for details.

By default, the CLI checks Maven Central on each run and auto-updates to the latest release. If your environment cannot reach Maven Central directly, you'll need to configure how the wrapper resolves and downloads versions — see air-gapped or restricted environments in the CLI wrapper guide.

Verify the installation by running mod --version.

For more on how the wrapper works (auto-update behavior, distribution URLs, JDK selection, environment variables), see the CLI wrapper and version management guide.

Step 3: Install recipe JARs​

With the CLI installed, the final piece is to stock it with recipes. This assumes the recipe JARs you want are already available in your internal artifact repository (per Step 1) — either because your mirror proxies Maven Central or because an administrator has synced them explicitly.

Run the mod config recipes jar install command and provide it with the JARs you wish to install. The latest version of every JAR, along with a ready-to-paste CLI install command, can be found at the bottom of the latest versions of every OpenRewrite module doc. This page is updated automatically with every release.

Next steps​