Roles

Roles provide a way to organize and reuse variables across user-defined commands.

By default, the Spring CLI includes an unnamed role that is always available. If no specific role is specified, commands use the default role.

To further customize and differentiate roles, you can associate them with specific names. These named roles are stored as YAML files within the .spring/roles directory, located alongside the .spring/commands directory.

Roles let you define variables that can be accessed in an action file by using Handlebars, letting you share data between commands.

Furthermore, you can use roles to supply values for command line options. If a command line option does not have a specified value and a role variable with the same name as the command option exists, the command automatically uses the value of the role variable for that specific option.

File Structure

For each role, a corresponding file is created in the .spring/roles/vars directory. For example, if there is a qa and prod role, the directory would look like the following:

$ tree .spring/roles/vars -lr
.spring/roles/vars
├── vars.yml
├── vars-qa.yml
└── vars-prod.yml

The vars.yml file is used for the default role.

This structure follows a similar pattern to using profile-specific Spring application configuration files. However, role variables do not exhibit the same behavior as Spring profiles, such as retrieving values from other locations in addition to the file (such as environment variables).

Quick Start

In this quick start, we demonstrate how to add variables to the default role and use their values when generating a file.

Let’s begin by setting the value of the role variable 'greeting' to 'Mondo':

$ spring role set --key greeting --value Mondo
Key-value pair added to the default role

The key-value pair is stored in the ./spring/roles/vars/vars.yml file under the root project directory.

To retrieve the value of the variable, use the following command:

$ spring role get --key greeting
Mondo

Now we create another role variable:

$ spring role set --key language --value Italian
Key-value pair added to the default role

Now we can incorporate these variables into a user-defined command. We create a user-defined command named hello say:

$ spring command new --command-name hello --sub-command-name say
Created user defined command /home/mark/testing-spring-cli/roles/myapp/.spring/commands/hello/say

Inside the .spring/commands/hello/say directory, you can find a file named command.yaml that has the following contents:

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

Note that the command line option name is greeting, which matches the name of the role variable we created.

Within the .spring/commands/hello/say directory, there is an action file named hello.yaml with the following contents:

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

Now we update the file to include:

actions:
  - generate:
      to: hello.txt
      text: Hello {{greeting}} on {{os-name}}. {{#if language}} {{language}} {{/if}}

When running the command without passing the greeting command-line option, the value of greeting is obtained from the role variable with the same name instead of using the default value of World.

Additionally, since we have defined the role variable language, we can test its existence and include its value in the output. Note that language is not a command line option. The following command (show with its output) does so:

$ spring hello say
Using Role variable instead of default command line option for key = greeting , value = Mondo from the default role
Generated /home/mark/testing-spring-cli/roles/myapp/hello.txt

The generated file contains:

Hello Mondo on Linux.  Italian

The value of {{greeting}} comes from the role variable because it was not provided as a command-line option.

The {{language}} variable was not a command line option, but it is available to use with Handlebars expressions.

Now we can remove the generated file. in the interactive shell, we run . ! rm hello.txt and pass in the greeting command line option:

$ spring hello say --greeting amico

The generated file contains:

Hello amico on Linux.  Italian

Setting Variables

To set a value for a role variable, use the spring role set command:

spring role set --key greeting --value Mondo

You can optionally specify the role by using the --role option.

Getting Variables

To retrieve the value of a role variable, use the following command:

spring role get --key greeting

You can optionally specify the role by using the --role option.

The role variable greeting can then be accessed inside action files that use Handlebars templating. See the quick start section for an example.

The role variable is also used to match against user-defined command option names. If a value is not explicitly provided as a command-line option, the value of the role variable is used.

You can also use the special command, . !, to view the full contents of the file that contains role variables when you are in the interactive shell:

spring:>. ! cat .spring/roles/vars/vars.yml
greeting: mondo

Adding a Role

To add a role, use the following command:

spring role add qa

This command creates a role named qa.

A file named ./spring/roles/vars/vars-qa.yml is created under the root project directory.

Listing Roles

To list the available roles, use the following command:

spring role list

This command displays the list of roles:

┌────┐
│Name│
├────┤
│qa  │
└────┘

Removing a Role

To remove a role, use the following command:

spring role remove qa

This command removes the role named qa.