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, pinned to a specific version, 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.2.10.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.

Step 3: Pin the CLI version​

The wrapper reads its global configuration from ~/.moderne/cli/dist/moderne-wrapper.properties. By default (when no version is configured), the wrapper resolves RELEASE against https://repo1.maven.org/maven2 — which won't work in an environment that cannot reach Maven Central directly.

Before running any mod command, pin the wrapper to the version you installed in Step 2:

echo "version=4.2.10" > ~/.moderne/cli/dist/moderne-wrapper.properties

Replace the version with the one you installed.

Pinning a version is required in environments that cannot reach repo1.maven.org. The wrapper's RELEASE and LATEST resolution always queries Maven Central for maven-metadata.xml, regardless of any distributionUrl setting. If Maven Central is not reachable and no version is pinned, every modw invocation will fail at version resolution.

There are two ways to upgrade the CLI later:

  • Re-run the installer (Step 2) for the new version, then update version= in this file.
  • Bump version= and let the wrapper download the new distribution. This requires also setting distributionUrl in this file to point at your internal mirror — see the air-gapped or restricted environments section of the CLI wrapper guide for the URL template. Once configured, you can also bump versions via mod wrapper --global --version=<new-version>.

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 4: Install recipe JARs​

With the CLI installed and pinned, 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​