For the latest stable version, please use Spring Cli 0.9.0!

Guide to User-defined Commands

User-defined commands let you add custom commands to the Spring CLI. The directory structure for commands represents the command and sub-command that are introduced into the shell.

For example, the directory structure of controller\new translates to the command controller new in the CLI.

The files located in the sub-command directory are:

A file named command.yaml that describes the command and its arguments.
One or more action files that describe the actions to take to add code or configuration to the project.

User-defined commands are registered with the CLI by using the following command:

command add --from <repository-url>

The contents of that repository are copied into your existing project.

For example, look at the contents of the github.com/rd-1-2022/udc-spring-controller repository.

Structure

The directory structure for all user-defined commands are under the following path:

.spring/commands

So, for the user defined command, controller new, mentioned previously, the full directory structure where the command description file and action files are located would be:

.spring/commands/controller/new

Inside this directory, you can define:

The command.yaml file that describes what the command does and the arguments of the command.
One or more action files that define the actions to run for this command.

For example, the directory contents of the github.com/rd-1-2022/udc-spring-controller repository are as follows:

.
├── README.adoc
└── .spring
    └── commands
        └── controller
            └── new
                ├── command.yaml
                ├── create-controller.yaml
                └── RestController.java

Describing the Command

The contents of the command.yaml file for the controller new command mentioned previously are as follows:

command:
  description: Generate a new Spring Controller
  options:
    #
    - name: feature
      description: name of the feature package
      dataType: string
      defaultValue: person
      inputType: text
      required: true

The file contains a brief description of the command and an array of command line options.

The name of the options is required. The default dataType is string.

The dataType can be int, integer, bool, boolean, double, float, long, short, or string.

Spring CLI incorporates these commands at runtime, and they appear when asking for general help and command-specific help. The following listing shows an example:

$spring help

<output truncated>

User-defined Commands
       controller new: Generate a new Spring Controller

The following listing show a second example:

$ spring help controller new
NAME
       controller new - Generate a new Spring Controller

SYNOPSIS
       controller new --feature String

OPTIONS
       --feature String
       name of the feature package
       [Optional, default = person]

Action Files

Action files are structured similarly to GitHub action files.

Action files can be named anything you like. The CLI looks for files with .yaml and .yml file extensions.

There can be as many action files as you need to accomplish a specific task. The order in which action files are run is depth-first and then alphabetical.

The following listing shows a simple example:

actions:
  - generate:
      to: hello.txt
      text: Hello at {{now}} on {{os-name}}.

This action generates a file called hello.txt, if it does not already exist, in the current working directory. The template contents contain kebab-case variable names.

The user-name and os-name variables come from Java system properties and are automatically registered with the template engine. The now variable is the value of new java.util.Date() when the command was run.

As a more realistic example to create Java code, the following three listings show the contents of the action file named Controller.java and its related action and templated Java files in the repository github.com/rd-1-2022/udc-spring-controller. The feature variable is a command option.

Command File

command:
  description: Generate a new Spring Controller
  options:
    #
    - name: feature
      description: name of the feature package
      dataType: string
      defaultValue: person
      inputType: text

Action File

actions:
  - generate:
      to: src/main/java/{{root-package-dir}}/{{feature}}/{{capitalizeFirst feature}}Controller.java
      from: RestController.java

The to: field defines the location of the file to be generated.

If the file to generate already exists, it is not overwritten unless an additional field named overwrite: is added at the same level as the to: field.

Templated Java File

package {{root-package}}.{{feature}};

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class {{capitalizeFirst feature}}Controller {

	@GetMapping("/{{feature}}")
	public String greeting() {
		return "Hello {{feature}}";
	}
}

All command-line arguments are passed to the template engine as variables. In this case, the feature option is passed.

One useful built-in variable is root-package-dir, which is the directory where the class containing the @SpringApplication annotation is located.

Template Engine

The template engine is Handlebars. Several Handlebar helpers are registered by default

In the previous example, the {{capitalizeFirst feature}} template variable is an example of using a Handlebars helper.

By default, several system variables are exposed to the template engine:

System.getProperties() is available as {{system-properties}}
System.getenv() is available as {{system-environment}}
The current time (defined by new Date().toString()) is available as {{now}}
The java.io.tmpdir system property is available as {{tmp-dir}}
The file.separator system property is available as {{file-separator}}* The os.name system property is available as {{os-name}}
The user.name system property is available as {{user.name}}

The Java package name where the Spring Boot main application class resides is available as {{root-package}}.

The directory where the Spring Boot main application class resides is available as {{root-package-dir}}.

The Maven model also exposes several variables:

{{artifact-id}}
{{artifact-version}}
{{artifact-path}}
{{project-name}}
{{project-descriptoin}}
{{maven-model} - This is the org.apache.maven.model.Model class.
{{maven-properties}} - This is a Java properties object that has, as keys, the values of each entry in the POM’s <properties> section.
{{java-version}} - This looks for a Maven Property named java.version in the POM. If the value is 1.8, it is converted to a value of 8.

Creating a New User-defined Command

A simple way to get started is to run the following command:

spring command new hello create

This creates a user-defined command named hello with a sub-command named create.

You can view the full set of options for spring command new by running spring command new --help. The following listing shows the output is:

$ spring command new --help
NAME
       command new - Create a new user-defined command

SYNOPSIS
       command new --commandName String --subCommandName String --path String --help

OPTIONS
       --commandName String
       The name of the user-defined command to create
       [Optional, default = hello]

       --subCommandName String
       The name of the user-defined sub-command to create
       [Optional, default = new]

       --path String
       Path to execute command in
       [Optional]

       --help or -h
       help for command new
       [Optional]

Running spring command new hello create generates the following directory structure and files.

.
├── README.adoc
└── .spring
    └── commands
        └── hello
            └── create
                ├── command.yaml
                └── hello.yaml

The following listing shows the contents of the command.yaml file. It contains one command line argument, named greeting.

command:
  description: Generate a new file with a hello message
  options:
    #
    - name: greeting
      description: who or what to say hello to
      dataType: string
      defaultValue: World
      inputType: text     # TEXT

The following listing shows the action file named hello.yaml. It generates the file named hello.txt

actions:
  - generate:
      to: hello.txt
      text: Hello {{greeting}} at {{now}} on {{os-name}}.

The command is listed under the User-defined Commands heading when you run the spring help command.

...
User-defined Commands
       hello create: Generate a new file with a hello message

Running the spring hello create command generates the hello.txt file with the following contents:

Hello World at Mar 9, 2023 on Linux.

Learning more

The Action Guide describes all the options available for you to use in action files (to add or modify code and configuration to a project).