Seed4J CLI

Description

Seed4J CLI is a command-line interface tool that helps you apply and manage Seed4J modules. It provides a modular approach to application generation, allowing you to select specific modules and features for your project. Visit Seed4J to learn more about it.

Quick Start

Make sure Java 25 or higher is available on your PATH, then install the seed4j command from npm:

npm install -g seed4j-cli
seed4j --help

You can also run it without a global install:

npx --package seed4j-cli seed4j --help

Then you can follow the Commands Guide

Prerequisites

Java

Java 25 or higher is a runtime requirement for seed4j-cli. The npm package runs the Seed4J CLI Spring Boot JAR with the first java available on your PATH:

• JDK 25

This requirement applies to the CLI itself, not to projects generated by Seed4J. Generated projects, including frontend-only projects, have their own runtime and toolchain requirements.

Node.js and NPM

Before you can build this project, you must install and configure the following dependencies on your machine:

Node.js: We use Node to run a development web server and build the project. Depending on your system, you can install Node either from source or as a pre-packaged bundle.

After installing Node, you should be able to run the following command to install development tools. You will only need to run this command when dependencies change in package.json.

npm install

Local environment

Start up

./mvnw

Build from source

Clone this project and go into the folder:

git clone https://github.com/seed4j/seed4j-cli
cd seed4j-cli

Build the Java package and prepare the npm package contents:

./mvnw --batch-mode -ntp clean package
npm run package:prepare

The preparation step copies the Maven-built JAR to dist/seed4j-cli.jar, which is the JAR shipped by npm.

To inspect the npm package before publishing:

npm pack --dry-run

To install the local package globally for a smoke test:

npm install -g .
seed4j --version

Release to npm

The npm package name is seed4j-cli, and it exposes the command seed4j.

Release Drafter keeps a draft GitHub Release updated from pull requests merged into main. The draft changelog is grouped by PR labels, so release notes are only as precise as the labels applied before merging.

The categories currently used by the draft are:

• theme: important
• area: feature request :bulb:
• area: enhancement :wrench:
• area: refactoring
• area: bug :bug:
• area: breaking change
• server: spring boot
• theme: security
• theme: maven
• theme: gradle
• area: documentation :books:
• area: remove
• area: invalid
• area: spam
• area: dependencies

pom.xml is the source of truth for the release version. Prepare a release by committing the Maven version and matching npm metadata, then push a tag with the same version:

git switch main
./mvnw versions:set -DnewVersion=0.0.2 -DgenerateBackupPoms=false
npm version 0.0.2 --no-git-tag-version
git add pom.xml package.json package-lock.json
git commit -m "chore(release): prepare 0.0.2"
git tag v0.0.2
git push origin main
git push origin v0.0.2

The release workflow reads the version from pom.xml, rejects snapshot versions, requires the tag to match v<project.version>, checks that package.json and package-lock.json match the Maven version, runs the wrapper tests, builds the JAR, prepares and smoke-tests the npm package, publishes with npm publish --provenance, then publishes the matching GitHub Release from the maintained draft. The GitHub Release attaches the versioned JAR, such as seed4j-cli-0.0.2.jar, but npm remains the primary installation channel:

npm install -g seed4j-cli

After the release is published, bump pom.xml, package.json, and package-lock.json to the next snapshot development version, for example 0.0.3-SNAPSHOT, in a follow-up commit.

Before the first Trusted Publishing release, configure the seed4j-cli package on npm with this GitHub publisher:

• Repository: seed4j/seed4j-cli
• Workflow: .github/workflows/release.yml
• Environment: leave empty unless the workflow is later changed to use one

If the package does not exist yet and npm requires a manual first publish, build from source, run npm run package:prepare, inspect npm pack --dry-run, then publish once from a maintainer machine with npm publish --provenance or, if provenance is not available locally, npm publish. After that, use the tag workflow for releases.

Usage

After the installation, you can use the seed4j with help command to know the options:

seed4j --help

To confirm the installed binary and embedded platform version:

seed4j --version

This prints both the Seed4J CLI version and the bundled Seed4J version.

To inspect module parameters before applying a module, add --plan:

seed4j apply init --plan

The plan first prints a Dependency plan, then the resolved text values and whether each value came from the current CLI input, project history, or a module metadata default. Lines marked with ✓ are resolved, and lines marked with ○ are pending or missing. Dependency statuses show direct module dependencies as already applied or pending; feature dependencies show either satisfied by <module> or pending choice with visible candidate modules. If required values are missing, it prints a Missing required parameters section and still does not apply files, write history, or create commits.

To install Bash completion for the active runtime:

seed4j completion bash --install
source ~/.local/share/bash-completion/completions/seed4j

The source command loads completion in the terminal session that is already open. Without it, open a new terminal so Bash loads the generated script during startup.

To inspect or install the script manually, redirect the generated output:

mkdir -p ~/.local/share/bash-completion/completions
seed4j completion bash > ~/.local/share/bash-completion/completions/seed4j

The generated script is static. Regenerate it after installing or changing an extension runtime, switching runtime mode, or changing hidden-resource configuration, then run source ~/.local/share/bash-completion/completions/seed4j again in the current terminal or open a new terminal.

By default, Bash completion includes static option value candidates from CLI metadata, known Seed4J module property values, and module default values. For example, seed4j apply init --project-name <TAB> can suggest "Seed4J Sample Application", seed4j apply init --node-package-manager <TAB> can suggest npm and pnpm, seed4j apply spring-boot --spring-configuration-format <TAB> can suggest yaml and properties, and seed4j apply init --end-of-line <TAB> can suggest lf and crlf. To generate a script without option value suggestions, use:

seed4j completion bash --no-complete-values --install

Value completion is limited to explicit static candidates in CLI metadata, known module property values, and module default values. It does not complete filesystem paths, shell history values, project history values, or values inferred from .seed4j.

To install or replace the active extension runtime:

seed4j extension install target/<your-extension-artifact>.jar --distribution-id my-company-extension --distribution-version 1.0.0

The install command validates the artifact, writes the active runtime files, and enables extension mode. You can also switch modes explicitly:

seed4j extension enable
seed4j extension disable

enable validates the active extension runtime before writing mode: extension. disable writes mode: standard, creates the config file when missing, and leaves the active extension JAR and metadata in place.

After installation, validate runtime activation with:

seed4j --version
seed4j list

Current limitation: seed4j extension disable uses the normal CLI bootstrap. It cannot recover automatically if a broken extension-mode configuration prevents the launcher from creating commands; in that case, set seed4j.runtime.mode: standard manually in ~/.config/seed4j-cli/config.yml.

Documentation

• Commands Guide
• Hexagonal architecture
• Package types
• Assertions
• sonar