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:
- 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 your
PATHsuch as a
- 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
mod [-h] [COMMAND]
Automated code remediation.
-h, --help Display this help message.
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
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.
study Produces studies from OpenRewrite recipe data tables
add Performs the equivalent of git add on multiple
apply Performs the equivalent of git apply on multiple
checkout Performs the equivalent of git checkout on multiple
clone Performs the equivalent of git clone on multiple
commit Performs the equivalent of git commit on multiple
exec Execute an arbitrary shell command recursively on
selected repository roots.
pull Performs the equivalent of git pull on multiple
push Performs the equivalent of git push on multiple
reset Performs the equivalent of git reset on multiple
rev-parse Performs the equivalent of git rev-parse on multiple
stashset, atomicstash Performs the equivalent of git stash on multiple
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 configand 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
~/.bashrcfile 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:
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.iowith 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 configand 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>
Below, we'll provide some context for the core commands.
buildcommand 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.
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/builddirectory inside of each repository that is built. The generated artifact will look similar to:
If you've set up a connection with Moderne (by running the
mod config modernecommand), the
buildcommand 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
buildcommand to look for LST artifacts in Moderne, you can add the
--no-downloadflag 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.
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 buildbefore you can run this command. You also must have set up an artifact repository connection via the
mod config artifactscommand.
runcommand 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 modernecommand. You'll also need to install recipes via the
mod config recipescommand. Lastly, you'll need to run
mod buildin 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 buildcommand). Likewise, the
mod runcommand 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.