Skip to main content

Module 1: CLI and LSTs

In this module, you'll set up everything the agent tools depend on: the Moderne CLI, a couple of recipe JARs (including io.moderne.recipe:rewrite-prethink), and Lossless Semantic Trees (LSTs) for a small working set of Java and Spring repositories. The later modules build on top of this setup, so don't skip ahead until your LSTs build cleanly.

Exercise 1-1: Install and configure the Moderne CLI​

Goals for this exercise​

  • Install the Moderne CLI on your machine
  • Authenticate the CLI against app.moderne.io
  • Confirm the installation by running mod --version

Steps​

Step 1: Install the CLI​

The recommended way to install the Moderne CLI is via the install script:

curl https://app.moderne.io/cli | bash

Alternatively, you can install via a package manager:

  • Homebrew (macOS/Linux): brew install moderneinc/moderne/mod
  • Chocolatey (Windows): choco install mod --prerelease

For more installation options, including Enterprise and Moderne DX setups, see Getting started with the Moderne CLI.

Verify the install:

mod --version

Step 2: Connect the CLI to Moderne​

Point the CLI at the public Moderne tenant and log in:

mod config moderne edit https://app.moderne.io
mod config moderne login

The login command opens a browser, asks you to grant the CLI access to your account, and stores a token locally that's valid for 365 days. If you're running on an Enterprise tenant, replace the URL with your tenant's hostname.

Restrictive networks

On corporate networks with proxies or limited Maven Central / Moderne SaaS access, see Using the CLI with internal tools and artifact repositories before continuing. Without a properly configured setup, you'll commonly see:

  • mod git sync moderne reports PARTIAL SUCCESS because a few LSTs sit on hosts your network can't reach
  • mod config recipes jar install fails to resolve a JAR — point it at your internal Artifactory/Nexus first via mod config recipes artifacts
  • mod build can't download Maven/Gradle plugins — set up your build tool's mirror and proxy as you normally would, then re-run

For the workshop you only need a handful of repos to succeed. Don't try to fix every failure up front.

Takeaways​

  • The Moderne CLI is the entry point for everything in this workshop. Every command you'll run starts with mod.
  • You only need to authenticate once. The CLI caches your token across terminal sessions.

Exercise 1-2: Install the recipe modules​

Goals for this exercise​

  • Install the recipe JARs needed for Prethink and the rest of this workshop
  • Understand the difference between mod config recipes jar install and a full catalog sync

Steps​

Step 1: Install the workshop recipe JARs​

Instead of syncing the entire recipe catalog, install just the JARs you need:

mod config recipes jar install \
  io.moderne.recipe:rewrite-prethink \
  org.openrewrite.recipe:rewrite-static-analysis \
  org.openrewrite.recipe:rewrite-spring

The rewrite-prethink artifact is the focus of this workshop: it uses an open-source org.openrewrite.recipe module for building blocks, while io.moderne.recipe:rewrite-prethink adds pre-configured discovery for Spring, JPA, Kafka, and other common frameworks. See Recipe modules for the full breakdown.

The other two JARs are useful warm-up recipes you'll touch later when verifying everything works.

tip

If you'd rather have the entire catalog available, run mod config recipes moderne sync instead. That takes a few minutes and downloads every recipe Moderne ships.

Step 2: Confirm the recipes are installed​

Search for one of the Prethink recipes to confirm it resolved:

mod config recipes search UpdatePrethinkContext

The CLI walks through each matching recipe interactively and asks whether to set it as the active recipe. You should see at least the io.moderne.prethink.UpdatePrethinkContextNoAiStarter and io.moderne.prethink.UpdatePrethinkContextStarter recipes show up. Press n (or just Enter) at each prompt to skip — you'll select recipes explicitly with --recipe later.

Takeaways​

  • mod config recipes jar install <coords> is a fast way to grab a known recipe pack without syncing the full catalog.
  • The Moderne Prethink module depends on the OpenRewrite Prethink module. Installing both is the safe default.

Exercise 1-3: Sync repositories and build LSTs​

Goals for this exercise​

  • Set up a workspace directory containing a few Java/Spring repositories
  • Build LSTs locally with mod build (the prerequisite for everything in the rest of this workshop)

Key concepts​

A Lossless Semantic Tree (LST) is a type-attributed, format-preserving tree representation of your source code. Recipes, the MCP server's semantic tools, and the Trigrep search index all read from LSTs rather than raw text, which is what gives them type awareness.

You can either download pre-built LSTs from the Moderne Platform or build them locally with mod build. Both options work for the rest of this workshop, but a local build is the more realistic flow for your own repositories. We'll show both paths.

Steps​

Step 1: Create a workspace directory​

mkdir ~/agent-tools-workshop
cd ~/agent-tools-workshop

This directory will hold the repositories, LSTs, search indexes, and recipe run artifacts for the rest of the workshop.

Step 2: Sync a small set of repositories​

Use the public Default organization, which contains a manageable mix of Java and Spring projects:

mod git sync moderne . --organization "Default" --with-sources

The --with-sources flag clones the source code in addition to fetching pre-built LSTs. Sources are required for the apply/commit steps in Module 3.

Sample sync output
● Synchronizing organization directory structure
Found 1 organization containing 11 repositories

● Downloading LSTs for repositories
  0% (1s)     ▶ awslabs/aws-saas-boost@main
  0% (1s)         ✗ Failed to download LST from http://artifactory.moderne.internal/...
  9% (1s)     ▶ apache/maven-doxia@master
  9% (1s)         ✓ Downloaded LST from https://artifactory.moderne.ninja/...
  ... (other repos)
100% (12s)    Done

Synced 11 repositories.

PARTIAL SUCCESS: mod partially succeeded with an exception
1 repository failed to sync. The exception for the failure on awslabs/aws-saas-boost@main is shown above.

A PARTIAL SUCCESS message is normal here — at the time of writing, one of the LSTs in the Default org is hosted on a Moderne-internal artifactory and isn't reachable from public networks. The 10 repos that did sync are enough for the workshop.

Reference: what gets synced

At the time of writing, the Default organization contains 11 public repositories spanning Maven, Gradle, and Spring projects:

  • apache/maven-doxia
  • awslabs/aws-saas-boost
  • finos/messageml-utils
  • finos/spring-bot
  • finos/symphony-bdk-java
  • finos/symphony-wdk
  • Netflix/photon
  • Netflix/ribbon
  • openrewrite/rewrite-recipe-bom
  • spring-projects/spring-data-commons
  • spring-projects/spring-petclinic

The exact list is updated occasionally, but it's always a small enough set to build locally without consuming much disk.

If you want a different mix (for example, only Spring repositories), browse the available organizations with mod config moderne organizations show and substitute a different name.

info

Don't worry if some LST downloads fail (you may see HTTP 404/401 messages, or skipped repos in the progress output). That's expected for a few of these public repos. Anything without an LST will be rebuilt locally in Step 3, and any repo whose build also fails is silently skipped. As long as a handful succeed, you're fine.

Step 3: Build any missing LSTs locally​

Run mod build on the workspace to (re)build LSTs for everything you just cloned:

mod build .

This invokes each project's build (Maven, Gradle, etc.) and serializes the LSTs to disk. On a small workspace it usually takes a couple of minutes. If a project fails to build, the CLI keeps going and just skips that one.

tip

If multiple projects fail with the same root cause, run mod trace builds analyze . --last-build to see a dashboard of build failures, with logs and per-repo details.

Step 4: Confirm LSTs are available​

mod list .

Repositories without LSTs are marked with a (no LST) annotation, like this:

  9% (1s)     ▶ awslabs/aws-saas-boost@main (no LST)
 18% (1s)     ▶ finos/messageml-utils@main
 27% (1s)     ▶ finos/spring-bot@spring-bot-master

As long as a handful of Java/Spring projects show up without that annotation, you're ready for the next module.

Takeaways​

  • The agent tools all build on top of LSTs. Without mod build (or downloaded LSTs), the MCP server's semantic tools, Prethink recipes, and Trigrep indexes have nothing to read.
  • You can mix and match: pre-built LSTs for repos available on the Moderne Platform and locally built LSTs for repos that aren't.
  • Build failures are normal in any heterogeneous set of repositories. Don't try to fix every failure right now. Move on as long as enough repos succeed.

Next up​

In Module 2, you'll install the Moderne skills and MCP server into your AI coding agent and see what new capabilities show up.