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 choose the outcome you need:

• Create a project with Seed4J modules
• Install the optional Seed4J CLI agent skill
• Look up an exact command, option, exit behavior, or configuration key
• Set up a contributor or maintainer environment
• Browse all documentation by audience

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.

Optional agent skill

Seed4J CLI remains fully usable without an agent skill. When a coding agent will use Seed4J as the project generator, install the bundled skill from the project directory so discovery stays local to that project:

seed4j skill install

The default destination is <current-working-directory>/.agents/skills/seed4j-cli. A first installation prints Installed Seed4J CLI skill at <absolute-path>.; a replacement prints Updated Seed4J CLI skill at <absolute-path>.. Use seed4j skill install --global only when you explicitly want the user-level destination <user-home>/.agents/skills/seed4j-cli.

The CLI owns the complete seed4j-cli destination. Updating replaces manual changes and stale files inside it while preserving sibling skills. Success exits 0, invalid usage exits 2, and an unexpected resource or filesystem failure exits 1 without a success line. The installation is offline: the skill bundled in CLI version X is the skill installed for version X.

An agent-oriented start looks like this:

seed4j skill install
Ask your coding agent: "Implement this new-project specification with Seed4J."

Restricted Codex workspace permissions can block writes to .agents and recursively protect .git. Run installation with Full Access or outside the restricted sandbox when required. For module execution with commits enabled, missing Git permission is fixed by changing the host permission; agents must not silently add --no-commit as a workaround.

Node.js and NPM

Node.js 22 or higher is required by the npm launcher and the development toolchain. See the contributor prerequisites for the supported version and dependency setup.

Local environment

Follow the local contributor workflow to install development dependencies and start the CLI.

Start up

The local startup command remains ./mvnw; the complete setup and validation path is in the contributor and maintainer guide.

Build from source

Use the canonical build-from-source procedure, including npm package inspection and the local smoke test.

Mutation testing

Mutation testing remains opt-in. See the PIT procedure and interpretation guidance.

Release to npm

The canonical npm release procedure owns versioning, Trusted Publishing, tag, workflow, and post-release instructions.

Usage

After installation, confirm the command and choose a goal:

seed4j --help

seed4j --version

• Apply one module or inspect its read-only plan
• Apply a validated module set or inspect its read-only preflight
• Create a project step by step
• Install Bash completion
• Install the optional agent skill
• Install or switch an extension runtime
• Look up options, configuration, and failure behavior

Documentation

• Documentation by audience
• Commands Guide
• Task workflows
• Contributor and maintainer guide
• Hexagonal architecture
• Package types
• Assertions
• Sonar