Comment on page
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:
To install the Moderne CLI please:
- 1.
- 2.Download the CLI for your operating system:
Mac
Linux
Windows
brew install moderneinc/moderne/mod
- 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
PATHto point to a specific location or this could involve putting it in a directory that's already on yourPATHsuch as a/usr/bindirectory. - 4.Ensure you can run the Moderne CLI by typing
mod. If everything is set up correctly, you should see a list of commands:
➜ moderne-cli git:(main) mod
▛▀▀▚▖ ▗▄▟▜
▌ ▜▄▟▀ ▐
▛▀▀█▀▛▀▀▀▀▜
▌▟▀ ▛▀▀▀▀▜
▀▀▀▀▀▀▀▀▀▀▀
Moderne CLI 1.7.0-SNAPSHOT
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.
list Lists the repositories that can be built and published.
publish Publishes the LST artifacts for a specific project.
run Runs an OpenRewrite recipe locally.
run-history
study Produces studies from OpenRewrite recipe data tables
locally.
add Performs the equivalent of git add on multiple
repositories.
apply Performs the equivalent of git apply on multiple
repositories.
checkout Performs the equivalent of git checkout on multiple
repositories.
clone Performs the equivalent of git clone on multiple
repositories.
commit Performs the equivalent of git commit on multiple
repositories.
exec Execute an arbitrary shell command recursively on
selected repository roots.
pull Performs the equivalent of git pull on multiple
repositories.
push Performs the equivalent of git push on multiple
repositories.
reset Performs the equivalent of git reset on multiple
repositories.
rev-parse Performs the equivalent of git rev-parse on multiple
repositories.
stashset, atomicstash Performs the equivalent of git stash on multiple
repositories.
generate-completion Generate bash/zsh completion script for mod.
MOD SUCCEEDED in (0.01s)
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)
Before you can run most commands, you'll need to configure 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.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>
If you want to publish artifacts from the CLI, you'll need to run the following command:
mod config artifacts edit <your-artifact-repository-url> --user <user> --password <password>
If you want to dive into using the CLI in a real-world situation, please check out our Moderne CLI exercise in the Spring Boot migration workshop. In there, you will work through using the CLI to migrate some Spring repositories from Spring Boot 2 to Spring Boot 3.
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.
To set up a pipeline that automatically builds and publishes LST artifacts for all of your repositories, please use the mod-connect tool.
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 using the mod-connect tool to set up Jenkins or GitHub actions for ingesting LST artifacts in bulk.
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.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 CI systems that we don't have a mod-connect command for. If you use Jenkins or GitHub, we strongly recommend using the mod-connect tool for building, publishing, and ingesting LST artifacts in bulk.
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 artifacts command.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.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.