Links

Getting started with the Moderne CLI

The Moderne CLI is a command line tool that allows you to build Lossless Semantic Tree (LST) artifacts, publish them to an artifact repository of your choosing, and run recipes from your local machine.
To ensure you can use the Moderne CLI successfully, in this guide, we will:

Installation

To install the Moderne CLI please:
  1. 1.
    Go to the Moderne platform and sign in.
  2. 2.
    Click on help in the bottom left-hand corner and select the version of the CLI you want to download. Then select the way you'd like to install it:
  1. 3.
    Regardless of how you downloaded the Moderne CLI, you'll need to save it somewhere that your terminal can access. This could involve updating your PATH to point to a specific location or this could involve putting it in a directory that's already on your PATH such as a /usr/bin directory.
Configuring the CLI mod command for Windows users using a JAR file:
If you use Git Bash and have a .bashrc file, you can add a function to it along the lines of:
mod() {
"java -jar /path/to/mod.jar" $@
}
If you use PowerShell, you can use the Set-Alias command within a profile script.
  1. 4.
    Ensure you can run the Moderne CLI by typing mod. If everything is set up correctly, you should see a list of commands:
mod command results
➜ moderne-cli git:(main) mod
▛▀▀▚▖ ▗▄▟▜
▌ ▜▄▟▀ ▐
▛▀▀█▀▛▀▀▀▀▜
▌▟▀ ▛▀▀▀▀▜
▀▀▀▀▀▀▀▀▀▀▀
Moderne CLI 2.8.1
Usage:
mod [-h] [COMMAND]
Description:
Automated code remediation.
Options:
-h, --help Display this help message.
Commands:
build Generates LST artifacts for one or more repositories.
clean Clean build and run artifacts produced by the CLI.
config Global configuration options that are required by some
CLI commands.
exec Execute an arbitrary shell command recursively on
selected repository roots.
git Multi-repository git operations.
list Lists the repositories that can be built and published.
publish Publishes the LST artifacts for one or more projects.
run Runs an OpenRewrite recipe locally on pre-built LSTS.
run-history Get information about the most recent recipe runs.
study Produces studies from OpenRewrite recipe data tables
locally.
generate-completion Generate bash/zsh completion script for mod.
MOD SUCCEEDED in (0.01s)

(Optionally) Set up auto-completion in your terminal (Unix terminals only)

The Moderne CLI offers a command which generates a completion script that can be used to set up auto-completion in your terminal. After initializing this script, you can type mod config and press tab and then your terminal will offer suggestions for the sub-commands or parameters:
To configure this for the terminal you're using please enter the following command in your terminal:
source <(mod generate-completion)
Or, if you want to configure auto-completion so that it works for every terminal instance you make, please update your ~/.zshrc or ~/.bashrc file and add this command to the bottom of it:
# The next line enables shell command completion for mod
source <(mod generate-completion)

Configuring the CLI

Before you can run most commands, you'll need to configure the CLI:

Create an access token and give it to the CLI

Go to https://app.moderne.io/settings/access-token, enter a human-readable name for the token (e.g., cli-token), and then press generate.
Once created, copy the token and use it in the following command:
mod config moderne edit https://app.moderne.io --token mat-YOUR_TOKEN_HERE
This command will set up the connection to Moderne so that you can install and run recipes. If you have a private tenant, you'll want to replace https://app.moderne.io with the link to your Moderne UI.

Install recipes

With the Moderne connection established, you can install recipes so you can run them locally by running the following command:
mod config recipes moderne sync
This will grab all of the recipes from the tenant you specified in mod config and download them to your machine so you can use the CLI to run them on your repositories.
If you want to install a specific recipe rather than all of the recipes, you can also do so by using the following command:
mod config recipes moderne install <recipe_search_term>

(Optionally) Configure artifact publishing

If you want to publish artifacts from the CLI, you'll need to run one of the following commands depending on if you want the LST artifacts published to Artifactory or to some location on disk:
# For JFrog Artifactory
mod config lsts artifacts artifactory edit <repository url> --user=${ARTIFACTS_USER} --password=${ARTIFACTS_PWD} ${ARTIFACT_REPOSITORY_URL}
# For other artifact repositories, such as Sonatype Nexus
mod config lsts artifacts maven edit <repository url> --user=${ARTIFACTS_USER} --password=${ARTIFACTS_PWD} ${ARTIFACT_REPOSITORY_URL}
OR
mod config lsts artifacts volume edit <location-on-disk>

Additional reading

Commands

For more details about the Moderne CLI and each of the commands, check out the Moderne CLI reference page.
Below, we'll provide some context for the core commands.

Build

The build command generates the LST artifacts for one or more projects. Once generated, the artifacts can be uploaded to your artifact management tool so that Moderne can ingest them - or - they can be used to run recipes locally.
While it is possible to manually build and publish your artifacts, we strongly recommend setting up a mass ingest job to do this in a VM.
If the path provided to this command is not a Git repository, then this command will recursively look through all the directories on the path for Git repositories. You can specify repository-* options to filter this to your needs.
If the command executes successfully, the LST artifact for each project will be stored in a .moderne/build directory inside of each repository that is built. The generated artifact will look similar to: spring-petclinic-20230919115358-ast.jar.
If you've set up a connection with Moderne (by running the mod config moderne command), the build command will attempt to download LST artifacts from Moderne instead of building them locally. This will allow you to quickly run recipes and make changes. If you do not want the build command to look for LST artifacts in Moderne, you can add the --no-download flag to the command.

Publish

The publish command allows you to manually publish LST artifacts for one or more projects. Once published to your artifact management tool, Moderne will be able to ingest them and they will, in turn, be usable inside of the SaaS.
This command is typically used for publishing LST artifacts from the mass ingest job you create in a VM.
You can also use this command for debugging purposes if you want to do a one-off test of uploading an artifact somewhere.
You must have run mod build before you can run this command. You also must have set up an artifact repository connection via the mod config lsts artifacts command.

Run

The run command allows you to run OpenRewrite recipes locally. Before you can run recipes, you'll need to create a Moderne access token and configure it via the mod config moderne command. You'll also need to install recipes via the mod config recipes command. Lastly, you'll need to run mod build in the repository/repositories where you want to run recipes.

Differences between the Moderne CLI and the OpenRewrite build plugins

The OpenRewrite build plugins are designed to run a single recipe on a single repository at a time. When you run a recipe using these plugins, a new LST is produced regardless of whether or not the code for that repository has changed. This LST is temporarily stored in memory and used by the recipe before being discarded at the end of the recipe run. For large projects, this can be problematic as the entire LST must fit in memory for the recipe to work.
In contrast, the Moderne CLI is designed for scale. You can run recipes against multiple repositories at once and the LST does not need to fit into memory. This is because the Moderne CLI uses proprietary code to build the LST up in parts and then serializes/writes it to the disk (as part of the mod build command). Likewise, the mod run command will read this LST from the disk in pieces as it runs recipes rather than building the LST every time.
When running the Moderne CLI commands for the first time, you might notice that running a single recipe on a single repository is slower than the OpenRewrite build plugins. This is due to the fact that the OpenRewrite build plugins do not serialize the LST and write it to disk.
However, if you wanted to run more recipes against the same LST, you would see that the Moderne CLI drastically increases in speed compared to the OpenRewrite build plugins as the Moderne CLI can read the pre-built LST and execute recipes against it rather than having to build it again each time. Furthermore, if you wanted to, you could use the Moderne CLI to run a recipe against many repositories at once – which the OpenRewrite build plugins can't do.