Firefly Framework CLI

 _____.__ _____.__
_/ ____\__|______ _____/ ____\ | ___.__.
\ __\| \_ __ \_/ __ \ __\| |< | |
| | | || | \/\ ___/| | | |_\___ |
|__| |__||__| \___ >__| |____/ ____|
\/ \/
_____ __
_/ ____\___________ _____ ______ _ _____________| | __
\ __\\_ __ \__ \ / \_/ __ \ \/ \/ / _ \_ __ \ |/ /
| | | | \// __ \| Y Y \ ___/\ ( <_> ) | \/ <
|__| |__| (____ /__|_| /\___ >\/\_/ \____/|__| |__|_ \
\/ \/ \/ \/

The official command-line interface for the Firefly Framework — scaffold, setup, diagnose, and manage your Firefly-based Java microservices with a world-class developer experience.

Quick Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/fireflyframework/fireflyframework-cli/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/fireflyframework/fireflyframework-cli/main/install.ps1 | iex

From Source

git clone https://github.com/fireflyframework/fireflyframework-cli.git
cd fireflyframework-cli
make install

Commands

`flywork setup`

Bootstraps the entire Firefly Framework into your local environment. Clones all 41 framework repositories in DAG-resolved dependency order and installs them to your local Maven cache (~/.m2).

The CLI resolves a dependency graph across all repositories, groups them into layers, and processes each layer sequentially to guarantee correct compilation order. Progress is shown with real-time progress bars, per-repo spinners with elapsed time, and a final summary box.

flywork setup # full interactive setup (prompts whether to run tests)
flywork setup --skip-tests # skip tests during Maven install
flywork setup --retry # retry only previously failed repositories
flywork setup --fresh # ignore previous manifest, start from scratch
flywork setup --fetch-updates # also fetch updates for already-cloned repos
flywork setup --jdk /path # use a specific JDK instead of auto-detection
flywork setup -v # verbose: show DAG layers and per-repo status

When --skip-tests is not provided, the CLI interactively asks whether to run tests (default: yes).

Flags:

Flag	Default	Description
`--skip-tests`	`false`	Skip running tests during Maven install
`--retry`	`false`	Retry only previously failed repositories
`--fresh`	`false`	Force a fresh setup, ignoring any previous manifest
`--fetch-updates`	`false`	Fetch latest changes for already-cloned repos
`--jdk`	`""`	Explicit JAVA_HOME path (skip JDK auto-detection)

What it does:

Preflight — Verifies Git, Maven, and Java are installed
Resume/Retry Detection — Detects previous setup manifest and offers to resume, retry, or restart
JDK Selection — Auto-detects installed JDK versions matching the configured java_version
Cloning — Resolves the dependency DAG (41 repos across 7 layers) and clones all repos layer-by-layer
Installing — Runs mvn clean install on each repo in dependency order with per-repo spinners
Post-Install Retry — If any repos fail, offers to retry them immediately
Displays a summary box with total time, repos cloned/installed, and layer count

`flywork create [archetype]`

Scaffolds a new project from one of four YAML-driven archetypes:

Archetype	Description
core	Multi-module microservice with R2DBC, Flyway, MapStruct, OpenAPI SDK
domain	Multi-module CQRS/Saga microservice with orchestration engine
application	Single-module application with plugin architecture
library	Single-module library with Spring Boot auto-configuration

flywork create # fully interactive mode
flywork create core # core archetype with prompts
flywork create domain --group-id com.example --artifact-id my-service
flywork create application -g com.example -a my-app -d "My Application"
flywork create library -g com.example -a my-lib --no-git
flywork create core --version 1.0.0 -o ./output-dir # custom version and output

If no archetype or flags are provided, the CLI enters interactive mode with prompts for archetype selection, group ID, artifact ID, package name, description, and infrastructure defaults.

Flags:

Flag	Short	Default	Description
`--group-id`	`-g`	`""`	Maven groupId (interactive if omitted)
`--artifact-id`	`-a`	`""`	Maven artifactId (interactive if omitted)
`--package`	`-p`	`""`	Base Java package (derived from groupId if omitted)
`--description`	`-d`	`""`	Project description
`--version`		`0.0.1-SNAPSHOT`	Initial project version
`--output`	`-o`	`""`	Output directory (defaults to artifactId)
`--no-git`		`false`	Skip git init

`flywork doctor`

Runs diagnostic checks against your environment:

Java version detection (configurable)
JAVA_HOME resolution
Maven version and Java compatibility
Git installation
Framework repositories cloned status
Parent POM / BOM presence in ~/.m2
Project structure validation
CLI version check

flywork doctor

`flywork update`

Pulls the latest changes for all framework repositories and reinstalls them to .m2, respecting DAG dependency order.

flywork update # pull + install all (prompts for tests)
flywork update --skip-tests # pull + install without tests
flywork update --pull-only # only git pull, skip maven
flywork update --repo fireflyframework-utils # single repo
flywork update -v # verbose with layer info

When --skip-tests is not provided (and not --pull-only), the CLI interactively asks whether to run tests (default: yes).

Flags:

Flag	Default	Description
`--pull-only`	`false`	Only git pull, skip Maven install
`--repo`	`""`	Update a single repository by name
`--skip-tests`	`false`	Skip running tests during Maven install

The update command uses the same DAG resolver as setup, with two distinct phases:

Phase 1 — Git pull with progress bar
Phase 2 — Maven install with per-repo spinners and elapsed time

`flywork build`

Smart DAG-aware build with SHA-based change detection. Detects which repos have changed since the last successful build, computes the transitive closure of affected downstream repos, and builds them in dependency order.

flywork build # build changed repos + affected dependents
flywork build --all # rebuild everything (ignore change detection)
flywork build --repo <name># build a specific repo and its dependents
flywork build --dry-run # show what would be built without building
flywork build --skip-tests # skip running tests during Maven install
flywork build --jdk /path # use an explicit JAVA_HOME

Flags:

Flag	Default	Description
`--all`	`false`	Rebuild everything (ignore change detection)
`--repo`	`""`	Build a specific repo and its dependents
`--dry-run`	`false`	Show what would be built without building
`--skip-tests`	`false`	Skip running tests during Maven install
`--jdk`	`""`	Explicit JAVA_HOME path

Phases:

Preflight — Verifies Git, Maven, and Java are installed
Change Detection — Compares HEAD SHAs against the last-build manifest (~/.flywork/build-manifest.json) and computes transitive closure over the DAG
Build Plan — Shows affected repos grouped by layer, marks directly changed repos with *
DAG Build — Runs mvn clean install layer-by-layer with progress bars and per-repo spinners
Summary — Reports built/skipped/failed counts, total time, and log locations for failures

`flywork publish`

Publishes Maven artifacts to GitHub Packages in DAG-resolved order. Uses the same change detection as build to only publish what has changed.

flywork publish # publish changed repos
flywork publish --all # publish everything
flywork publish --repo <name># publish a specific repo
flywork publish --dry-run # show what would be published
flywork publish --skip-tests # skip tests during deploy (default: true)
flywork publish --jdk /path # use an explicit JAVA_HOME

Flags:

Flag	Default	Description
`--all`	`false`	Publish everything (ignore change detection)
`--repo`	`""`	Publish a specific repo only
`--dry-run`	`false`	Show what would be published without publishing
`--skip-tests`	`true`	Skip tests during deploy
`--jdk`	`""`	Explicit JAVA_HOME path

Requires GITHUB_TOKEN environment variable set with write:packages scope.

Phases:

Preflight — Verifies GITHUB_TOKEN, Git, Maven, and Java
Maven Settings — Ensures ~/.m2/settings.xml contains the GitHub Packages server configuration
Publish Plan — Shows repos to publish grouped by layer
Maven Deploy — Runs mvn deploy layer-by-layer with progress bars
Summary — Reports published/skipped/failed counts and total time

`flywork dag`

Inspect and query the framework dependency graph. Useful for understanding build order, debugging dependency issues, and CI/CD integration.

flywork dag show # display full graph as ASCII tree
flywork dag layers # show repos grouped by build layer
flywork dag affected --from <repo># compute transitive closure of affected repos
flywork dag affected --from <repo> --json # machine-readable output
flywork dag export# export full DAG as JSON for CI/CD consumption

Subcommands:

Subcommand	Description
`show`	Full dependency graph with arrows showing dependencies
`layers`	Repos grouped by build layer (0 = no dependencies)
`affected`	Transitive closure of repos affected by a change in `--from` (required flag)
`export`	JSON export of the entire DAG (nodes, edges, layers) for CI/CD

`flywork fwversion`

Manage framework-wide CalVer versions across all repositories. CalVer format: YY.MM.PP (e.g., 26.02.07).

flywork fwversion show # show current version across all repos
flywork fwversion bump --auto # auto-compute next CalVer and bump all POMs
flywork fwversion bump --auto --push # bump, commit, tag, and push
flywork fwversion bump --dry-run # preview changes without modifying files
flywork fwversion bump --install # bump + run mvn install after
flywork fwversion check # validate version consistency across repos
flywork fwversion families # show version family release history

Subcommands:

Subcommand	Description
`show`	Displays current POM versions, mismatches, dirty trees, and config alignment
`bump`	Updates all `pom.xml` files across every repo, optionally commits, tags, and pushes
`check`	Runs consistency checks: POM versions, config match, git tags, clean trees, `.m2` artifacts
`families`	Shows version family history — each bump records a snapshot of module SHAs

Bump flags:

Flag	Default	Description
`--auto`	`false`	Auto-compute next CalVer from current version
`--commit`	`true`	Git commit the version changes
`--tag`	`true`	Git tag each repo with `v<version>`
`--push`	`false`	Git push after commit/tag
`--dry-run`	`false`	Show changes without modifying files
`--install`	`false`	Run `mvn install` in all repos after bumping

`flywork release`

Orchestrates an end-to-end framework release across every Java repo. Walks the dependency DAG layer-by-layer: pushes release branches, opens PRs with auto-merge, waits for CI, admin-merges on review-gate, tags main with v<version>, waits for the release workflow's GitHub Packages publish, then re-triggers CIs on the next layer so downstream PRs pick up newly-published artifacts.

flywork release Auto-compute next CalVer; orchestrate end-to-end
flywork release --year 26 --month 5 --patch 8 Explicit target version
flywork release --from-layer 3 Resume cascade starting at layer 3
flywork release --dry-run Print plan only, no changes
flywork release --skip-prs Push directly to main (skip PR step, advanced)
flywork release --repo X Limit to a single repo (still respects DAG order)

Subcommands:

Subcommand	Description
`status`	Per-repo release state (✓ released, ⏳ tagged but publish in flight, blank for pending)
`verify`	3-column status: git tag / GitHub Packages / Maven Central — for any version via `--version`
`publish-mvn-central`	Trigger Maven Central publish workflow (`workflow_dispatch`) for repos missing from Central — retries Sonatype Portal polling timeouts without re-tagging

Cascade flags:

Flag	Default	Description
`--year` / `--month` / `--patch`	auto	Explicit CalVer parts (otherwise next patch is computed)
`--dry-run`	`false`	Print plan without making changes
`--skip-prs`	`false`	Push directly to main (skip PR step)
`--skip-tag`	`false`	Do not tag main (skip release trigger)
`--from-layer`	`0`	Resume cascade starting at this DAG layer (0-indexed)
`--admin`	`true`	Use `--admin` to bypass branch protection / required reviews
`--timeout-minutes`	`30`	Per-layer timeout in minutes for the github-packages wait
`--repo`	`""`	Limit to a single repo (still respects DAG order)

verify flags:

Flag	Default	Description
`--version`	config	Version to verify (defaults to `config.parent_version`)

publish-mvn-central flags:

Flag	Default	Description
`--version`	config	Version to publish
`--repo`	`""`	Limit to a single repo
`--wait-seconds`	`3600`	Sonatype Central polling wait time (seconds) — Portal validation can take 20–40 min

Maven Central architecture:

Maven Central publishing is decoupled from the main release workflow (in fireflyframework/.github/.github/workflows/). Each repo has two workflows:

release.yml → calls reusable java-release.yml → GH Packages publish + GitHub Release page (fast, deterministic, completes in ~90s)
maven-central.yml → calls reusable java-publish-maven-central.yml → Sonatype Portal publish (slow, up to 60 min; can be retried via workflow_dispatch without re-tagging)

This means a slow Sonatype validation no longer blocks the fast GitHub Packages publish or the Release page creation. Retry independently via:

flywork release publish-mvn-central --version 26.05.07 --repo fireflyframework-plugins

`flywork run`

Runs a Firefly Framework application with interactive configuration assistance. Detects the Spring Boot module, scans configuration files for missing environment variables, and launches an interactive wizard before starting the app.

flywork run # interactive run with configuration wizard
flywork run --profile dev # activate the 'dev' Spring profile
flywork run --skip-wizard # skip the configuration wizard
flywork run --profile local --skip-wizard # non-interactive run with 'local' profile

What it does:

Project Analysis — Detects archetype (core, domain, application, library), multi-module layout, and locates the web/boot module
Profile Selection — If Spring profiles are detected (e.g. dev, local) and --profile is not provided, offers an interactive selection prompt
Configuration Scanning — Parses application.yaml for ${PLACEHOLDER} variables and groups them into: set from environment, have defaults, or missing (required)
Interactive Wizard — Prompts for required variables, offers to override defaults, and uses smart defaults for common names (e.g. DB_HOST → localhost, DB_PORT → 5432)
Launch — Starts the application with mvn spring-boot:run passing the selected profile and environment variable overrides

Flags:

Flag	Default	Description
`--profile`	`""`	Spring profile to activate (e.g. dev, local)
`--skip-wizard`	`false`	Skip the interactive configuration wizard

`flywork upgrade`

Self-updates the CLI binary from GitHub releases.

flywork upgrade # download and install latest version
flywork upgrade --check # just check if an update is available

Flags:

Flag	Default	Description
`--check`	`false`	Only check for updates, don't install

`flywork config`

View and manage CLI configuration stored in ~/.flywork/config.yaml.

flywork config # show all configuration
flywork config get java_version # get a single value
flywork config set java_version 25 # set a value
flywork config set parent_version 1.0.0-SNAPSHOT
flywork config reset # reset to defaults

`flywork version`

Prints CLI version, git commit, build date, Go version, and OS/architecture.

flywork version

Global Flags

Flag	Short	Description
`--verbose`	`-v`	Enable verbose output (DAG layers, per-repo details, etc.)
`--help`	`-h`	Show help for any command

The --verbose flag is available on all commands. It enables additional output such as DAG layer headers, per-repo status lines, and detailed version information.

DAG Dependency Resolution

The CLI maintains an internal directed acyclic graph of all 41 framework repositories with their real Maven dependency relationships. This ensures:

Correct build order — repositories are always compiled after their dependencies
Layer grouping — independent repos are grouped into layers for potential parallelization
Cycle detection — the DAG engine detects and reports circular dependencies with the exact cycle path

Dependency layers:

Layer	Repositories
0 (1)	`parent`
1 (10)	`bom`, `utils`, `cache`, `eda`, `ecm`, `idp`, `config-server`, `client`, `validators`, `plugins`, `observability`
2 (9)	`r2dbc`, `cqrs`, `web`, `orchestration`, `ecm-esignature-adobe-sign`, `ecm-esignature-docusign`, `ecm-esignature-logalty`, `ecm-storage-aws`, `ecm-storage-azure`, `idp-aws-cognito`, `idp-keycloak`
3 (6)	`eventsourcing`, `application`, `idp-internal-db`, `core`, `domain`, `data`
4 (5)	`webhooks`, `callbacks`, `notifications`, `rule-engine`, `backoffice`
5 (4)	`notifications-firebase`, `notifications-resend`, `notifications-sendgrid`, `notifications-twilio`

Configuration

Configuration is stored in ~/.flywork/config.yaml.

Key	Default	Description
`repos_path`	`~/.flywork/repos`	Where framework repos are cloned
`github_org`	`fireflyframework`	GitHub organization name
`default_group_id`	`org.fireflyframework`	Default Maven groupId for new projects
`java_version`	`25`	Target Java version for compilation
`parent_version`	`26.05.07`	Parent POM CalVer version for archetypes
`cli_auto_update`	`false`	Auto-check for CLI updates on launch
`branch`	`develop`	Git branch to clone during setup

Dynamic Java Version

The CLI automatically detects installed Java versions:

macOS — Uses /usr/libexec/java_home -v <version>
Linux — Scans /usr/lib/jvm/ and update-alternatives
Windows — Scans Program Files\Java, Eclipse Adoptium, Corretto, etc.

Change the required Java version:

flywork config set java_version 25

All setup and update commands will automatically resolve the correct JAVA_HOME for that version.

Archetype System

Built-in Archetypes

Archetypes are YAML-driven definitions embedded in the CLI binary. Each archetype defines:

Module structure — multi-module or single-module layout
Parent POM — inherited from fireflyframework-parent
Dependencies — per-module Maven dependencies
Plugins — Maven plugins (Spring Boot, MapStruct, OpenAPI Generator, etc.)
Templates — Go template files rendered with project metadata
Package layout — Java package directories to create

Customizing Archetypes

You can override any built-in archetype or create new ones by placing YAML files in:

~/.flywork/archetypes/

For example, to customize the core archetype:

mkdir -p ~/.flywork/archetypes
vim ~/.flywork/archetypes/core.yaml

The YAML structure follows this schema:

name: my-archetypedescription: Description of the archetypemultiModule: trueparent:
groupId: org.fireflyframeworkartifactId: fireflyframework-parentversion: 1.0.0-SNAPSHOTmodules:
- suffix: interfacesdescription: Shared DTOs and contractspackages:
- dtos
- enumsdependencies:
- { groupId: "org.fireflyframework", artifactId: "fireflyframework-utils" }templates:
- { src: "core/interfaces-pom.xml.tmpl", dest: "pom.xml" }rootTemplates:
- { src: "shared/gitignore.tmpl", dest: ".gitignore" }
- { src: "shared/README.md.tmpl", dest: "README.md" }

Creating New Archetypes

Create a YAML file in ~/.flywork/archetypes/<name>.yaml
Define modules, dependencies, and template references
Place corresponding .tmpl template files in the templates directory
Use Go template variables: {{.ProjectName}}, {{.ArtifactId}}, {{.GroupId}}, {{.BasePackage}}, {{.PackagePath}}, {{.Version}}, {{.JavaVersion}}, {{.Year}}, etc.
Run flywork create <name> to use your custom archetype

Uninstall

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/fireflyframework/fireflyframework-cli/main/uninstall.sh | bash

Windows

irm https://raw.githubusercontent.com/fireflyframework/fireflyframework-cli/main/uninstall.ps1 | iex

Development

Prerequisites

Go 1.25+
Make

Build Targets

make build # build for current platform → bin/flywork
make install # build + install to /usr/local/bin
make test# run tests
make vet # run go vet
make clean # remove build artifacts
make build-all # cross-compile for 6 platforms (darwin/linux/windows × amd64/arm64)
make release # build-all + create .tar.gz / .zip archives
make checksums # release + SHA256 checksums

Project Structure

fireflyframework-cli/
├── cmd/ # Cobra command definitions
│ ├── root.go # Root command, banner, global flags
│ ├── setup.go # flywork setup (DAG + TUI)
│ ├── create.go # flywork create (interactive scaffolding)
│ ├── doctor.go # flywork doctor (environment checks)
│ ├── update.go # flywork update (DAG + TUI)
│ ├── build.go # flywork build (smart DAG build)
│ ├── publish.go # flywork publish (GitHub Packages deploy)
│ ├── dag.go # flywork dag (graph inspection)
│ ├── fwversion.go # flywork fwversion (CalVer management)
│ ├── release.go # flywork release (DAG-ordered cascade + verify + publish-mvn-central)
│ ├── upgrade.go # flywork upgrade (self-update)
│ ├── config.go # flywork config (get/set/reset)
│ ├── run.go # flywork run (application runner)
│ └── version.go # flywork version
├── internal/
│ ├── build/ # Smart build engine
│ │ ├── builder.go # DAG-ordered build execution
│ │ ├── changes.go # SHA-based change detection
│ │ └── manifest.go # Build manifest (last-known SHAs)
│ ├── config/config.go # YAML config management
│ ├── dag/graph.go # DAG engine (topological sort, layers, cycle detection)
│ ├── doctor/checks.go # Diagnostic checks
│ ├── git/git.go # Git operations
│ ├── java/java.go # Cross-platform Java detection
│ ├── maven/maven.go # Maven operations with JAVA_HOME support
│ ├── publish/ # Publish engine
│ │ ├── publisher.go # DAG-ordered Maven deploy
│ │ ├── python.go # Python package publishing
│ │ └── settings.go # Maven settings.xml management
│ ├── runner/ # Application runner with config wizard
│ ├── scaffold/ # Archetype engine
│ │ ├── engine.go # Template rendering and project generation
│ │ ├── archetypes/*.yaml # Embedded archetype definitions
│ │ └── templates/* # Embedded Go templates
│ ├── selfupdate/updater.go # CLI self-update from GitHub releases
│ ├── setup/ # Setup operations
│ │ ├── cloner.go # DAG-ordered git clone
│ │ └── installer.go # DAG-ordered maven install
│ ├── version/ # Framework version management
│ │ ├── calver.go # CalVer parsing and computation
│ │ ├── bumper.go # POM version bumping across all repos
│ │ ├── checker.go # Version consistency validation
│ │ └── families.go # Version family tracking and history
│ └── ui/ # TUI components
│ ├── printer.go # Styled output, spinners, progress bars, summary boxes
│ └── prompt.go # Interactive prompts
├── install.sh # curl | bash installer (macOS/Linux)
├── install.ps1 # irm | iex installer (Windows)
├── uninstall.sh # Uninstaller (macOS/Linux)
├── uninstall.ps1 # Uninstaller (Windows)
├── Makefile # Build targets for 6 platforms
├── go.mod / go.sum
├── LICENSE # Apache License 2.0
└── main.go # Entry point

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github/workflows		.github/workflows
cmd		cmd
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
flywork		flywork
go.mod		go.mod
go.sum		go.sum
install.ps1		install.ps1
install.sh		install.sh
main.go		main.go
uninstall.ps1		uninstall.ps1
uninstall.sh		uninstall.sh

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Firefly Framework CLI

Quick Install

macOS / Linux

Windows (PowerShell)

From Source

Commands

flywork setup

flywork create [archetype]

flywork doctor

flywork update

flywork build

flywork publish

flywork dag

flywork fwversion

flywork release

flywork run

flywork upgrade

flywork config

flywork version

Global Flags

DAG Dependency Resolution

Configuration

Dynamic Java Version

Archetype System

Built-in Archetypes

Customizing Archetypes

Creating New Archetypes

Uninstall

macOS / Linux

Windows

Development

Prerequisites

Build Targets

Project Structure

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`flywork setup`

`flywork create [archetype]`

`flywork doctor`

`flywork update`

`flywork build`

`flywork publish`

`flywork dag`

`flywork fwversion`

`flywork release`

`flywork run`

`flywork upgrade`

`flywork config`

`flywork version`