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 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 using the command

command add --from <repository-url>

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

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

Structure

The directory structure for all user defined commands are under the 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 file command.yaml that describes what the command does and the arguments of the command * One or more Action Files that define the actions to execute for this command.

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

.
├── 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 is:

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, and string.

The CLI incorporates these commands at runtime and appear when asking for general help and the command help.

$spring help

<output truncated>

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

and

$ 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 structred similar to GitHub Action files.

Acitons files can be named anything you like, the CLI will look for files with a .yaml or .yml file extension

There can be as many action files as you need to accomplish a specific task. The order of Action Files execution is depth first and alphabetical.

Here is a very simple example

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

This will generate the file hello.txt, if it does not already exist, in the current working directory. The template contents contains kebab-case variable names.

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

As a more realistic example to create Java code, the Action File named Controller.java in the repository github.com/rd-1-2022/udc-spring-controller is shown below. 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

Templated Java File

The file RestController.java is a templated text file shown below:

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}}";
	}
}

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

If the file to generate already exists, it will not be overwritten unless the additional field overwrite: at the same level of generate is added at the same level of the to: field.

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

One of the useful built-in variables 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 template variable {{capitalizeFirst feature}} is an example of using a Handlebar helper

Several system variables are exposed to the template engine by default.

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

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

The directory where the Spring Boot main applicaiton class resides is available under {{root-package-dir}}

The Maven model exposes several variables:

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

Creating a new user defined command

A simple way to get started is to run the command

spring command new hello create

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

You can view the full set of options for spring command new by executing spring command new --help. The output is shown below.

$ 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]

Executing spring command new hello create generates following directory structure and files as discussed previously.

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

The contents of the command.yaml file is shown below. 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

And the action file hello.yaml is shown below. 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 heading User-defined Commands when executing the command spring help.

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

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

Hello World at Mar 9, 2023 on Linux.

Learning more

The section Action Guide describes all the options available for you to use in Action Files to add or modify code and configuration to a project.