fractalx-cli · v0.1.0

Generate Spring Boot projects
from your terminal

An interactive 6-step wizard that scaffolds a modular monolith pre-annotated with FractalX decomposition markers. Run fractalx, answer a few questions, get a ZIP.

Install View on GitHub

zsh

$ fractalx

FractalX CLI

Generate a Spring Boot monolith ready for decomposition

Step 1 — Project

Group ID: com.acme

Artifact ID: shop-platform

Java version: 21

Step 2 — Services

+ order-service (pg, port 8081)

+ payment-service (pg, port 8082)

✔ shop-platform.zip

Installation

Three ways to install

Pick the method that fits your workflow. All three install the same fractalx binary.

Homebrew

macOS & Linux

brew install fractalx-org/tap/fractalx-cli

Updates automatically with brew upgrade fractalx-cli. Recommended for macOS users.

curl

macOS & Linux

curl -fsSL …/install.sh | sh

Auto-detects OS and architecture. Downloads the right binary from GitHub Releases into /usr/local/bin.

Go install

Any platform

go install github.com/fractalx-org/fractalx-cli@latest

Requires Go 1.21+. Works on Windows, macOS, and Linux. Builds directly from source.

Or download a binary directly from GitHub Releases — available for macOS, Linux, and Windows.

Usage

Flags & options

Run fractalx with no flags to launch the interactive wizard.

Flag	Default	Description
--from <file>	—	Load a `fractalx.yaml` spec file and skip the wizard entirely. Useful for re-generation and CI pipelines.
--output <dir>	.	Directory where the ZIP archive (or project folder) is written.
--no-zip	false	Write files directly to disk as a folder instead of a ZIP archive.
--help	—	Print usage information.

# Interactive wizard

fractalx

# Regenerate from a saved spec

fractalx --from fractalx.yaml --no-zip

# Save ZIP to a specific folder

fractalx --output ~/projects

The Wizard

6 steps, fully guided

Each step maps directly to a layer of your generated project. Skip a step or accept defaults — everything has sensible values out of the box.

Step 01

Project

Maven coordinates, Java version, and Spring Boot version. Sets the package name, app class, and parent POM.

groupId artifactId javaVersion springBootVersion

Step 02

Services

Define bounded-context services. Each gets a port, database, and optional JPA or MongoDB entities with typed fields.

h2 postgresql mysql mongodb redis

Step 03

Dependencies

Choose which services call which. Circular dependencies are detected via DFS — generation is blocked if any cycle exists.

cross-module calls cycle detection

Step 04

Sagas

Optional. Configure distributed sagas — owner service, compensation method, and ordered steps across services.

@DistributedSaga compensation steps

Step 05

Infrastructure

Toggle components to include: API Gateway, Admin Dashboard, Service Registry, Docker Compose, GitHub Actions CI, Kubernetes, Observability, and Saga Orchestrator.

docker k8s ci otel

Step 06

Security

Pick an authentication strategy. The right Spring Security dependencies and config stubs are added automatically.

none jwt oauth2 apikey

fractalx.yaml

Re-generate without the wizard

Every generated project includes a fractalx.yaml spec. Edit it and pass it to --from to regenerate at any time — useful for adding services, changing databases, or running in CI.

fractalx.yaml round-trip spec

project:
  groupId: com.acme
  artifactId: shop-platform
  version: "1.0.0-SNAPSHOT"
  javaVersion: "21"
  springBootVersion: 3.3.0

services:
  - name: order-service
    port: 8081
    database: postgresql
    entities:
      - name: Order
        fields:
          - totalAmount: BigDecimal
          - status: String
  - name: payment-service
    port: 8082
    database: postgresql
    dependencies: [order-service]

infrastructure:
  gateway: true
  docker: true
  ci: github-actions
  observability: true

security:
  type: jwt

# Edit fractalx.yaml, then regenerate
fractalx --from fractalx.yaml --no-zip --output ./regenerated

Next steps

After generation

The generated project is a standard Spring Boot Maven project. Run it like any other — or decompose it immediately.

Unzip and enter the project

The CLI writes a .zip archive by default. Unzip and cd into it, or use --no-zip to skip the archive entirely.

# unzip and enter
unzip shop-platform.zip && cd shop-platform

Start infrastructure

If you selected Docker Compose in the wizard, a docker-compose.dev.yml is included with all database and observability containers.

# start databases + observability
docker compose -f docker-compose.dev.yml up -d

Run the monolith

The project boots as a regular Spring Boot app on the dev profile. All services are wired together in a single JVM.

mvn spring-boot:run -Dspring-boot.run.profiles=dev

Decompose into microservices

When you're ready to scale, FractalX reads the @DecomposableModule markers and generates a fully wired microservice platform in one command.

# generate production microservices
mvn fractalx:decompose

Ready to scaffold?

Install the CLI, run fractalx, and have a decomposition-ready Spring Boot project in under a minute.

Install now Use the web UI instead →

Apache 2.0 · Go binary · No telemetry · Runs offline

Generate Spring Boot projectsfrom your terminal