The Moderne CLI has always been a powerful way to run OpenRewrite recipes across many repositories. But with version 3.45, it becomes something much bigger: a platform for sharing structure, state, and context across teams, business units, and the entire organization. This release introduces a fundamental shift in how transformations are executed and coordinated, pushing the CLI from a local tool to an organization-aware engine for change.
Prior to this release, when you cloned an organization from the Moderne SaaS Platform or Moderne DX, it was cloned into a flat local directory structure with all the sub-orgs landing in the same local directory. This made it challenging to re-subset or re-separate data produced by repositories into organizational units again.
From now on, the CLI clones into a hierarchical directory structure that reflects the organizational structure. In addition, we are adding the capabilities to the CLI to clone organizations directly from a repos.csv file rather than from the Moderne Platform. CLI commands that clone, build, and publish LSTs now also produce and update an effective repos.csv file, which can be hosted centrally across the team or the entire organization to facilitate sharing. In particular, repos.csv makes it easier to build and share LSTs across team members for non-default branches that are not built by the platform/central team.
Read on to learn more about this milestone Moderne CLI release.
Organizing code for collaboration
One of the biggest shifts in 3.45 is how the CLI represents repositories in your organization. With mod git sync, the CLI now aligns your local directory structure with the organizational structure. Repositories are grouped into folders that reflect your organizational hierarchy, however it is configured—subteam, business unit, product line, or the entire company.
The legacy mod git clone command has been deprecated in favor of mod git sync, which does more than just cloning code. It synchronizes the local directory structure with your source of truth, downloading both repository metadata, LSTs, and optionally the source code itself (using --with-sources). Each directory gains a .moderne/repos-lock.csv file, capturing the exact state of the repository: branch, commit, artifact location, and organizational placement. It’s the Moderne CLI equivalent of npm’s package-lock.json, ensuring that anyone else syncing the same file ends up with the same structure and metadata. We call this effective repos.csv.
To produce an effective repos.csv, start with mod git sync, build and publish commands working with an initial repos.csv that must contain, at a minimum, a cloneUrl field for repos and organizations that you want to clone. You can produce this starter repos.csv using Moderne’s repository fetchers. As you run the commands, they will write out changesets, branches, artifact location URLs, and other metadata to produce effective repos.csv that can be shared.
Because the CLI operates on LSTs, collaboration doesn’t require a full source code clone of every repo. Many workflows run entirely on the structured metadata. For example:
- Analyze change impact via data tables using
mod study. - Feed AI/code agents like Moddy without needing the source tree.
- Explore diffs and proposed changes from recipe runs before opening a PR or committing code.
- Test and iterate while developing custom recipes, using LSTs to validate transformations before rollout.
From one CLI to many teams
The CLI is now deeply aware of organizational boundaries. Commands like mod run, mod study, and mod devcenter have been enhanced to produce outputs on disk that reflect the org hierarchy.
You can run these commands from any level of the directory structure, targeting all sub-orgs at the root, or limiting the scope using a simple cd command and running it from lower levels of the tree. Each command produces outputs recursively for each org and sub-org from the level at which it was run. That means better scoping and clearer ownership when running and sharing reports.
But it’s not just about running recipes across organizations, it’s also about how teams contribute to and reuse the recipes themselves. To support inner-source practices, Moderne CLI makes it simple to distribute and install custom recipes. Use mod config recipes export to generate a catalog of available recipes for documentation or internal portals. Or share your custom recipes as .jar files that colleagues can install with mod config recipes jar install.
All of these improvements make the CLI especially valuable for:
- Development leaders tracking modernization or migration progress (using custom dashboards generated by
mod devcenter) - Product teams evaluating what changes are coming and why they matter
- Central platform teams comparing rollouts across business units
Reporting and traceability as first-class features
CLI workflows at scale demand observability. With 3.45, Moderne introduces structured trace files that persist across every major phase: sync, build, run. These trace.json or trace.csv files, as shown in the example JSON file below, capture both activity and failure information, and propagate errors forward so they can be debugged in context.
For example:
- If a repo fails to clone, that failure is also visible in the build and run traces.
- If a build fails, its error details are preserved into the run trace.
- Trace files include metadata about the build, making it possible to analyze and group failures across repositories based on build configuration.
- Raw build logs are still available to aggregate and valuable for deeper inspection.
{
"run": {
"success": true,
"startTime": "2025-09-15T09:54:19.10332+02:00",
"endTime": "2025-09-15T09:54:33.010087+02:00",
"log": "file:///organizations/Default/apache/maven-doxia/.moderne/run/20250915095414-Vlzu9/run.log",
"id": "20250915095414-Vlzu9",
"unlicensedAttempt": false,
"streaming": false,
"recipeId": "org.openrewrite.java.migrate.UpgradeToJava21",
"recipeInstanceName": "Migrate to Java 21",
"recipeOptions": null,
"recipeArtifact": "org.openrewrite.recipe:rewrite-migrate-java:3.17.0-SNAPSHOT",
"estimatedEffortTimeSavingsMs": 6600000,
"dependencyResolutionTimeMs": 40,
"filesWithFixResults": 22,
"filesWithSearchResults": 22,
"filesWithErrors": 0,
"filesSearched": 316,
"dataTables": 17,
"elapsedTimeMs": 13907
},
"build": {
"success": true,
"startTime": "2025-09-12T10:34:58.363534Z",
"endTime": "2025-09-12T10:35:59.869382Z",
"log": "file:///organizations/Default/apache/maven-doxia/.moderne/build/20250912123457-Umb2J/build.log",
"id": "20250912123457-Umb2J",
"changeset": "e8f43962f2db5c3ca3bc3d86026936bfcacab5dd",
"dependencyResolutionTimeMs": 59160,
"mavenVersion": "3.9.10",
"gradleVersion": null,
"bazelVersion": null,
"dotnetVersion": null,
"pythonVersion": null,
"nodeVersion": null,
"sourceFileCount": 316,
"lineCount": 51715,
"parseErrorCount": 0,
"weight": 10102,
"maxWeight": 2575,
"maxWeightSourceFile": "doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownSinkTest.java",
"elapsedTimeMs": 61506
},
"clone": {
"success": true,
"cloneUri": "https://github.com/apache/maven-doxia",
"startTime": "2025-09-12T10:28:33.337877Z",
"endTime": "2025-09-12T10:28:36.215196Z",
"log": "file:///organizations/Default/apache/maven-doxia/.moderne/sync/sync.log",
"changeset": "e8f43962f2db5c3ca3bc3d86026936bfcacab5dd",
"elapsedTimeMs": 2878
},
"org": "ALL/Default",
"repository": {
"origin": "github.com",
"path": "apache/maven-doxia",
"branch": "master",
"partition": null
}
}
The mod log runs command aligns with these trace files to produce structured, spreadsheet-friendly reports. And for visual inspection, mod trace builds analyze can launch a local web-based viewer of build failure data. In the future, more commands will produce traces, and mod trace will also be extended beyond just builds to work with runs and more.
This makes it easier to do postmortems, audits, and troubleshooting. Teams can even wrap the CLI in a shell script and use it to wire up a BI integration and ship the data to their specific reporting platform. For example, a Moderne CLI wrapper script could integrate with an ELK stack (Elasticsearch, Logstash, Kibana) to collect and visualize telemetry data, as in this example.
Performance and polish
To keep up with growing repo volumes and complex orgs, 3.45 also introduces several under-the-hood improvements:
- Parallel by default: no more sequential mass runs unless explicitly configured
- Treeless and single-branch clones: speed up cloneing and significantly reduce network and disk usage
- Improved output styling: supports richer terminals with OSC-8 links, extended UTF-8 characters, and better formatting and color-coded text
These changes make the CLI more responsive and usable as both an interactive and automated tool.
A CLI built for large-scale modernization
Version 3.45 turns the Moderne CLI into more than just a tool for running recipes. It becomes a tool for coordinating transformation across an organization. It supports the way modern teams work: distributed, fast-moving, and deeply interconnected.
It’s also a glimpse into the future. The same CLI developers use locally will drive backend workers in the Moderne Platform. Whether you're transforming code from a terminal, a CI job, or a dashboard, it's powered by the same core workflows.
Now the Moderne CLI isn’t just for running recipes, it’s for running transformation.
Download the Moderne CLI and learn more in the documentation.
