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:
Go to the Moderne platform and sign in.
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:
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 yourPATH
such as a/usr/bin
directory.
Ensure you can run the Moderne CLI by typing
mod
. If everything is set up correctly, you should see a list of commands:
(Optional) 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:
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:
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:
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:
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:
If you have private recipe artifacts and want to point the CLI to them, please run the following command:
(Optional) Configure artifact publishing and downloading
If you want to publish artifacts from the CLI or download LSTs from your artifact repository when running commands, you'll need to run one of the following commands depending on where your LST artifacts live:
(Optional) Configure a license key
If you are wanting to run the CLI against private repositories you will need to configure a license.
(Optional) Configure a Maven settings file
If you have a Maven settings file that exists outside of your repositories, you can use the following command to point the CLI to it. This ensures dependencies are resolved the same as builds:
(Optional) Configure recipe sources
If you have custom recipes you want to include in the CLI, you will need to let the CLI know about them:
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.
Find all of the parameters for the build command here
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.
Find all of the parameters for the publish command here
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.
Find all of the parameters for the run command here
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.
Last updated