Commands Reference

Complete reference for all Spring-Hex CLI commands. Commands are organized by category for easier navigation.

Table of Contents

  1. Commands Reference
    1. Setup Commands
      1. init
    2. Hexagonal Architecture Commands
      1. make:mediator
      2. make:module
      3. make:command
      4. make:query
      5. make:model
      6. make:entity
      7. make:aggregate
      8. make:value-object
      9. make:event
      10. make:port
      11. make:adapter
      12. make:repository
      13. make:mapper
      14. make:controller
      15. make:request
      16. make:response
    3. Data Seeding Commands
      1. make:factory
      2. make:seeder
      3. db:seed
    4. CRUD Commands
      1. make:crud
    5. Test Commands
      1. make:test
      2. run:test
    6. Migration Commands
      1. make:migration
      2. migrate
      3. migrate:rollback
      4. migrate:status
      5. migrate:validate
      6. migrate:repair
      7. migrate:fresh

Setup Commands

init

Setup

Initialize a .hex/config.yml configuration file in the current project.

Usage:

spring-hex init [options]
Option Description
--force Overwrite existing configuration file
-p, --package Specify base package (auto-detected if not provided)
-o, --output Output directory for config file (defaults to current directory)

Example:

spring-hex init
spring-hex init --force -p com.mycompany.app

Generated File: Creates .hex/config.yml with default path configurations for both hexagonal and CRUD architectures.

Hexagonal Architecture Commands

make:mediator

Hexagonal

Generate the mediator infrastructure for CQRS command and query buses.

Usage:

spring-hex make:mediator [options]
Option Description
-p, --package Base package (auto-detected if not specified)
-o, --output Output directory (defaults to current directory)

Example:

spring-hex make:mediator

Generated Files:

  • CommandBus interface
  • SimpleCommandBus implementation
  • QueryBus interface
  • SimpleQueryBus implementation
  • MediatorConfig Spring configuration class

make:module

Hexagonal

Generate a complete hexagonal module with domain, application, and infrastructure layers.

Usage:

spring-hex make:module <moduleName> [options]
Parameter Required Description
<moduleName> Yes Name of the module/aggregate (e.g., order, user)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:module order

Generated Structure: Creates a complete package structure with domain, application ports, and infrastructure directories ready for development.

make:command

Hexagonal

Generate a CQRS command and its handler.

Usage:

spring-hex make:command <commandName> -a <aggregate> [options]
Parameter Required Description
<commandName> Yes Name of the command (e.g., CreateOrder)
-a, --aggregate Yes Aggregate name (e.g., order)
--no-handler No Skip generating the command handler
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:command CreateOrder -a order
spring-hex make:command UpdateOrderStatus -a order --no-handler

Generated Files:

  • Command class (e.g., CreateOrderCommand)
  • Command handler class (e.g., CreateOrderCommandHandler) - unless --no-handler is specified
  • Command handler interface (e.g., CreateOrderCommandHandlerInterface)

make:query

Hexagonal

Generate a CQRS query and its handler.

Usage:

spring-hex make:query <queryName> -a <aggregate> [options]
Parameter Required Description
<queryName> Yes Name of the query (e.g., GetOrderById)
-a, --aggregate Yes Aggregate name (e.g., order)
--no-handler No Skip generating the query handler
-r, --return-type No Return type for the query handler (defaults to void)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:query GetOrderById -a order -r OrderDTO
spring-hex make:query ListOrders -a order --return-type "List<OrderSummary>"

Generated Files:

  • Query class (e.g., GetOrderByIdQuery)
  • Query handler class (e.g., GetOrderByIdQueryHandler) - unless --no-handler is specified
  • Query handler interface (e.g., GetOrderByIdQueryHandlerInterface)

make:model

Hexagonal

Generate a domain model class.

Usage:

spring-hex make:model <modelName> -a <aggregate> [options]
Parameter Required Description
<modelName> Yes Name of the model (e.g., Order, Customer)
-a, --aggregate Yes Aggregate name (e.g., order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:model Order -a order
spring-hex make:model OrderItem -a order

Generated Files:

  • Domain model class in the appropriate aggregate package

make:entity

Hexagonal

Generate a JPA entity for persistence.

Usage:

spring-hex make:entity <entityName> -a <aggregate> [options]
Parameter Required Description
<entityName> Yes Name of the entity (e.g., OrderEntity)
-a, --aggregate Yes Aggregate name (e.g., order)
--table No Database table name (defaults to snake_case of entity name)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:entity OrderEntity -a order
spring-hex make:entity OrderEntity -a order --table orders

Generated Files:

  • JPA entity class with @Entity and @Table annotations

make:aggregate

Hexagonal

Generate an aggregate root with ID value object.

Usage:

spring-hex make:aggregate <aggregateName> [options]
Parameter Required Description
<aggregateName> Yes Name of the aggregate (e.g., Order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:aggregate Order

Generated Files:

  • Aggregate root class
  • ID value object (e.g., OrderId)

make:value-object

Hexagonal

Generate a domain value object.

Usage:

spring-hex make:value-object <name> -a <aggregate> [options]
Parameter Required Description
<name> Yes Name of the value object (e.g., Money, Email)
-a, --aggregate Yes Aggregate name (e.g., order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:value-object Money -a order
spring-hex make:value-object OrderStatus -a order

Generated Files:

  • Immutable value object class with equality based on value

make:event

Hexagonal

Generate a domain event and its listener.

Usage:

spring-hex make:event <eventName> -a <aggregate> [options]
Parameter Required Description
<eventName> Yes Name of the event (e.g., OrderCreated - “Event” suffix auto-appended)
-a, --aggregate Yes Aggregate name (e.g., order)
--no-listener No Skip generating the event listener
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:event OrderCreated -a order
spring-hex make:event OrderStatusChanged -a order --no-listener

Generated Files:

  • Domain event class (e.g., OrderCreatedEvent)
  • Event listener class (e.g., OrderCreatedEventListener) - unless --no-listener is specified

make:port

Hexagonal

Generate a port interface (input or output).

Usage:

spring-hex make:port <portName> -a <aggregate> [options]
Parameter Required Description
<portName> Yes Name of the port interface (e.g., OrderRepository)
-a, --aggregate Yes Aggregate name (e.g., order)
--in No Generate as input port (default is output port)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:port OrderRepository -a order
spring-hex make:port CreateOrderUseCase -a order --in

Generated Files:

  • Port interface in the appropriate port package (input or output)

make:adapter

Hexagonal

Generate an adapter implementing a port.

Usage:

spring-hex make:adapter <adapterName> -a <aggregate> --port <portName> [options]
Parameter Required Description
<adapterName> Yes Name of the adapter (e.g., JpaOrderRepository)
-a, --aggregate Yes Aggregate name (e.g., order)
--port Yes Port interface name that this adapter implements
--category No Adapter category subdirectory (e.g., persistence, messaging)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:adapter JpaOrderRepository -a order --port OrderRepository
spring-hex make:adapter JpaOrderRepository -a order --port OrderRepository --category persistence

Generated Files:

  • Adapter class implementing the specified port interface

make:repository

Hexagonal

Generate a repository port and adapter with Spring Data support.

Usage:

spring-hex make:repository <entityName> -a <aggregate> [options]
Parameter Required Description
<entityName> Yes Name of the entity (e.g., Order)
-a, --aggregate Yes Aggregate name (e.g., order)
-s, --store No Data store type: jpa (default), mongodb, or redis
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:repository Order -a order
spring-hex make:repository Order -a order -s mongodb
spring-hex make:repository Session -a auth -s redis

Generated Files:

  • Repository port interface
  • Repository adapter implementation
  • Spring Data repository interface (JPA/MongoDB/Redis specific)

make:mapper

Hexagonal

Generate a mapper for converting between domain models and persistence entities.

Usage:

spring-hex make:mapper <entityName> -a <aggregate> [options]
Parameter Required Description
<entityName> Yes Name of the entity (e.g., Order)
-a, --aggregate Yes Aggregate name (e.g., order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:mapper Order -a order

Generated Files:

  • Mapper class with methods to convert between domain model and entity

make:controller

Hexagonal

Generate a REST controller for an aggregate.

Usage:

spring-hex make:controller <aggregate> [options]
Parameter Required Description
<aggregate> Yes Aggregate name (e.g., order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:controller order

Generated Files:

  • REST controller class with @RestController and basic endpoint structure

make:request

Hexagonal

Generate a request DTO for API endpoints.

Usage:

spring-hex make:request <requestName> -a <aggregate> [options]
Parameter Required Description
<requestName> Yes Name of the request (e.g., CreateOrder - “Request” suffix auto-appended)
-a, --aggregate Yes Aggregate name (e.g., order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:request CreateOrder -a order
spring-hex make:request UpdateOrderStatus -a order

Generated Files:

  • Request DTO class (e.g., CreateOrderRequest) with validation annotations

make:response

Hexagonal

Generate a response DTO for API endpoints.

Usage:

spring-hex make:response <responseName> -a <aggregate> [options]
Parameter Required Description
<responseName> Yes Name of the response (e.g., OrderDetails - “Response” suffix auto-appended)
-a, --aggregate Yes Aggregate name (e.g., order)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:response OrderDetails -a order
spring-hex make:response OrderSummary -a order

Generated Files:

  • Response DTO class (e.g., OrderDetailsResponse)

Data Seeding Commands

make:factory

Data

Generate a data factory class using Datafaker for creating fake entity instances.

Usage:

spring-hex make:factory <entityName> [options]
Parameter Required Description
<entityName> Yes Entity class name (e.g., UserEntity, BookEntity)
-a, --aggregate No Aggregate name (defaults to entity name lowercase, “Entity” suffix stripped)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:factory UserEntity
spring-hex make:factory OrderItemEntity -a order

Generated Files:

  • Factory @Component implementing Factory<T> interface with make() and repository()
  • Factory<T> interface (auto-generated once, on first factory creation)
  • JPA repository interface (auto-generated if one doesn’t already exist)
  • Uses Datafaker for realistic fake data

Usage in Code:

// Inject the factory (it's a Spring component)
@Autowired
private UserEntityFactory userEntityFactory;

// create() saves one entity to database and returns it
UserEntity user = userEntityFactory.create();

// count(n).create() saves n entities and returns a List
List<UserEntity> users = userEntityFactory.count(50).create();

// make() creates in memory only (useful for unit tests)
UserEntity transient = userEntityFactory.make();

// count(n).make() creates n entities in memory
List<UserEntity> transients = userEntityFactory.count(10).make();

// Nested factories: create() persists dependencies automatically
// In BookEntityFactory.make():
//   .author(authorEntityFactory.create())   // author saved first

Note: Add net.datafaker:datafaker to your project dependencies to use factories.

make:seeder

Data

Generate a database seeder class for populating development and test data.

Usage:

spring-hex make:seeder <seederName> --entity <entityName> [options]
Parameter Required Description
<seederName> Yes Seeder name (e.g., UserSeeder — “Seeder” suffix auto-appended)
--entity Yes Entity class name for factory import (e.g., UserEntity)
-a, --aggregate No Aggregate name (defaults to entity name lowercase, “Entity” suffix stripped)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:seeder UserSeeder --entity UserEntity
spring-hex make:seeder OrderItemSeeder --entity OrderItemEntity -a order

Generated Files:

  • Seeder class implementing Seeder interface with a seed() method
  • Seeder interface (auto-generated once, on first seeder creation)
  • SeedRunner infrastructure component (auto-generated once, on first seeder creation)

Execution Order:

The SeedRunner contains an ordered list of seeder classes. When running db:seed --all, seeders execute in the order they appear in the list. Add your seeders in dependency order — independent entities first:

private static final List<Class<? extends Seeder>> SEEDERS = List.of(
        AuthorSeeder.class,    // no dependencies — runs first
        BookSeeder.class       // depends on Author — runs second
);

db:seed

Data

Run database seeders via the project’s build tool.

Usage:

spring-hex db:seed <seederName>
spring-hex db:seed --all
Parameter Required Description
<seederName> No Seeder class name to run (e.g., UserSeeder)
--all No Run all seeders

Example:

spring-hex db:seed UserSeeder
spring-hex db:seed --all

Behavior:

  • Detects Maven or Gradle and runs the Spring Boot application with --seed=<target> argument
  • The auto-generated SeedRunner picks up the argument and invokes the matching seeder’s seed() method
  • --all runs all seeders listed in SeedRunner.SEEDERS in the order they appear

CRUD Commands

make:crud

CRUD

Generate a complete CRUD implementation with model, repository, service, and controller.

Usage:

spring-hex make:crud <entityName> [options]
Parameter Required Description
<entityName> Yes Name of the entity (e.g., User, Product)
--no-model No Skip generating the model/entity
--no-service No Skip generating the service layer
--resources No Generate CRUD endpoints and service methods ready for development
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:crud Product
spring-hex make:crud Product --resources
spring-hex make:crud Category --no-model

Generated Files:

  • Entity class with JPA annotations
  • Repository interface extending JpaRepository
  • Service class with CRUD operations
  • REST controller with CRUD endpoints
  • Mapper class for DTO conversion

Test Commands

make:test

Testing

Generate a test class (unit or feature test).

Usage:

spring-hex make:test <name> [options]
Parameter Required Description
<name> Yes Name of the class being tested (e.g., OrderService)
--unit No Generate unit test (default is feature/integration test)
-p, --package No Base package (auto-detected if not specified)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:test OrderService --unit
spring-hex make:test OrderController

Generated Files:

  • JUnit test class with appropriate annotations and setup

run:test

Testing

Execute tests using Maven or Gradle.

Usage:

spring-hex run:test [options]
Option Description
--unit Run only unit tests
--feature Run only feature/integration tests

Example:

spring-hex run:test
spring-hex run:test --unit
spring-hex run:test --feature

Migration Commands

make:migration

Migration

Generate a database migration file.

Usage:

spring-hex make:migration <migrationName> [options]
Parameter Required Description
<migrationName> Yes Descriptive name for the migration (e.g., create_orders_table)
--flyway No Generate Flyway migration (default)
--liquibase No Generate Liquibase changeset
--format No Format for Liquibase: sql, xml, or yaml (default: sql)
-o, --output No Output directory (defaults to current directory)

Example:

spring-hex make:migration create_orders_table
spring-hex make:migration add_status_column --liquibase --format xml

Generated Files:

  • Flyway: Versioned SQL file with timestamp prefix (e.g., V20260210123045__create_orders_table.sql)
  • Liquibase: Changeset file in specified format with master changelog update

migrate

Migration

Run all pending database migrations.

Usage:

spring-hex migrate

Behavior:

  • Executes all pending migrations using the configured migration tool (Flyway or Liquibase)
  • Updates migration history tracking

migrate:rollback

Migration

Rollback the last migration or multiple migrations.

Usage:

spring-hex migrate:rollback [options]
Option Description
--step Number of migrations to rollback (default: 1)

Example:

spring-hex migrate:rollback
spring-hex migrate:rollback --step 3

Note: Rollback support varies by migration tool. Flyway requires undo migrations.

migrate:status

Migration

Display the status of all migrations.

Usage:

spring-hex migrate:status

Output: Shows which migrations have been applied, pending migrations, and migration history.

migrate:validate

Migration

Validate applied migrations against available migration files.

Usage:

spring-hex migrate:validate

Behavior:

  • Checks for migration file modifications
  • Validates checksums
  • Reports any inconsistencies

migrate:repair

Migration

Repair the migration history table.

Usage:

spring-hex migrate:repair

Use Cases:

  • Fix checksum mismatches
  • Remove failed migration entries
  • Repair corrupted migration history

migrate:fresh

Migration

Drop all tables and re-run all migrations.

Usage:

spring-hex migrate:fresh --force
Option Required Description
--force Yes Required safety flag to confirm destructive operation

Warning: This command destroys all data in the database. Use only in development environments.

Example:

spring-hex migrate:fresh --force

Back to top

Spring Hex CLI — Hexagonal Architecture scaffolding for Spring Boot

This site uses Just the Docs, a documentation theme for Jekyll.