Spring Shell

https://github.com/spring-projects/spring-shell
Admin
Spring Shell is a framework that provides an easy way to build powerful command-line applications in...
Tokens:28,582
Snippets:341
Trust Score:9.7
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Hello world view example using TerminalUI

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/intro/index.adoc

Simple Spring Shell Terminal UI example that prints 'hello world' in a view. Uses TerminalUI as the class handling all view logic and View as the root view.

```java
include::{snippets}/TerminalUiSnippets.java[tag=introsample]
```

--------------------------------

### ButtonView implementation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/button.adoc

Example of setting text and an action for a ButtonView.

```java
include::{snippets}/ButtonViewSnippets.java[tag=sample]
```

--------------------------------

### Example shell interaction

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/getting-started.adoc

Sample output showing the help command, the custom hello command, and exiting the shell.

```text
$>help
Available commands:
Built-In Commands
	clear: Clear the terminal screen
	help: Display help about available commands
	version: Show version info
Greetings
	hello: Say hello to a given name

$>hello --name=foo
Hello foo!
$>exit
Exiting the shell
```

--------------------------------

### Run the application with Java

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-samples/spring-shell-sample-petclinic/README.md

Run this command to start the application. After running, you should see a prompt where you can enter commands.

```bash
java -jar spring-shell-samples/spring-shell-sample-petclinic/target/petclinic.jar
```

--------------------------------

### MenuBarView construction in Java

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/menubar.adoc

Example of constructing a MenuBarView using MenuBarItem and MenuItem instances.

```java
include::{snippets}/MenuBarViewSnippets.java[tag=snippet1]
```

--------------------------------

### Simple SearchMatch usage example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/appendices/techintro/searchalgorithm.adoc

Shows a simple usage example of SearchMatch. The exact code is not visible on this page; it is included from an external snippet file.

```java
include::{snippets}/SearchAlgorithmsSnippets.java[tag=simple]
```

--------------------------------

### Example command invocation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

Example command invocation showing options in long and short form, with arguments interspersed. Options always expect a value, even for booleans.

```shell
$>mycommand mysubcommand --optionA=value1 arg1 -b=value2 arg2 --optionC value3 -d value4
```

--------------------------------

### Use JLineShellRunner with Spring Boot starter

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Shows a Spring Boot application that starts the JLine-based interactive shell. The comment indicates that SpringApplication.run starts the JLine-based interactive shell. This requires the Spring Boot starter that configures JLineShellRunner.

```java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.shell.core.command.annotation.Command;

@SpringBootApplication
public class SpringShellApplication {

	public static void main(String[] args) {
        // This will start the JLine-based interactive shell
		SpringApplication.run(SpringShellApplication.class, args);
	}

	@Command
	public void hi() {
		System.out.println("Hello world!");
	}

}
```

--------------------------------

### GridView usage example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/grid.adoc

Example of using GridView to layout other views. The resulting layout is shown as a grid of cells.

```java
include::{snippets}/GridViewSnippets.java[tag=snippet1]
```

--------------------------------

### Multi Select Component Example (UiComponentSnippets.java)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/components/ui/multiselect.adoc

Example of using the multi select component. The code is from the `UiComponentSnippets.java` file, tagged with `snippet7`. The context object is `MultiItemSelectorContext`.

```java
include::{snippets}/UiComponentSnippets.java[tag=snippet7]
```

--------------------------------

### JLine style spec mode examples

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/appendices/techintro/theming.adoc

Examples of style mode specs: bold alone and bold with a foreground color.

```text
bold
bold,fg:red
```

--------------------------------

### Define command with input reading

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/testing.adoc

Example of a command that reads input from the user via the command context.

```java
@Bean
public Command ask() {
    return new AbstractCommand("ask", "Ask for user input") {
        @Override
        public ExitStatus doExecute(CommandContext commandContext) throws Exception {
            String message = commandContext.inputReader().readInput();
            commandContext.outputWriter().println("You said: " + message);
            return ExitStatus.OK;
        }
    };
}
```

--------------------------------

### Number Input Component Example (Java)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/components/ui/numberinput.adoc

Shows how to use the number input component. The component asks for a simple number input and can be configured to use any implementation of Number.class.

```java
include::{snippets}/UiComponentSnippets.java[tag=snippet10]
```

--------------------------------

### Run the secure input sample application

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-samples/spring-shell-sample-secure-input/README.md

Executes the built JAR file to start the Spring Shell application. After startup, you can use 'auth login' to authenticate with username 'foo' and password 'bar'.

```bash
java -jar spring-shell-samples/spring-shell-sample-secure-input/target/secure-input.jar
```

--------------------------------

### Testing Multiple Commands with ShellTestClient

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/testing.adoc

This example demonstrates a Spring Boot application with multiple commands and a corresponding test class using @ShellTest and @SpringBootTest to verify command execution.

```java
@SpringBootApplication
public class GreetingShellApplication {

	public static void main(String[] args) {
		SpringApplication.run(GreetingShellApplication.class, args);
	}

	@Command
	public void hi(CommandContext context) {
		context.outputWriter().println("Hello world!");
	}

	@Command
	public void bye(CommandContext context) {
		context.outputWriter().println("Goodbye world!");
	}

}

@ShellTest
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE,
		useMainMethod = SpringBootTest.UseMainMethod.ALWAYS, classes = { GreetingShellApplication.class },
		properties = { "spring.shell.interactive.enabled=false" })
public class ShellApplicationEndToEndMultipleCommandsTests {

	@Test
	void testCommandExecution(@Autowired ShellTestClient client) throws Exception {
		// when
		ShellScreen shellScreen = client.sendCommand("help");

		// then
		ShellAssertions.assertThat(shellScreen).containsText("AVAILABLE COMMANDS");
	}

	@Test
	void testHiCommandExecution(@Autowired ShellTestClient client) throws Exception {
		// when
		ShellScreen shellScreen = client.sendCommand("hi");

		// then
		ShellAssertions.assertThat(shellScreen).containsText("Hello world!");
	}

	@Test
	void testByeCommandExecution(@Autowired ShellTestClient client) throws Exception {
		// when
		ShellScreen shellScreen = client.sendCommand("bye");

		// then
		ShellAssertions.assertThat(shellScreen).containsText("Goodbye world!");
	}

}
```

--------------------------------

### Shell output for unavailable command

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/availability.adoc

Example output when the download command is invoked while not connected, showing the availability explanation.

```shell
shell:>download
Command 'download' exists but is not currently available because you are not connected.
```

--------------------------------

### EventLoop keyEvents filtering example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/events/eventloop.adoc

Shows how to select key events using the built-in filtering method _keyEvents()_.

```java
include::{snippets}/EventLoopSnippets.java[tag=keyevents]
```

--------------------------------

### InputView usage example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/input.adoc

Illustrates how to use InputView in a Java snippet, but the actual code is included from an external file and not visible on this page.

```java
include::{snippets}/InputViewSnippets.java[tag=sample]
```

--------------------------------

### JLine ANSI escape code examples

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/appendices/techintro/theming.adoc

Examples of plain ANSI escape codes using numbers separated by semicolons.

```text
31
31;1
```

--------------------------------

### Clone and build Spring Shell from source

Source: https://github.com/spring-projects/spring-shell/blob/main/README.adoc

Clones the Spring Shell repository, changes to the project directory, and builds with Maven wrapper. This installs the project artifacts locally.

```bash
$>git clone git@github.com:spring-projects/spring-shell.git
$>cd spring-shell
$>./mvnw install
```

--------------------------------

### v4 ExitStatusExceptionMapper example

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Shows the new v4 way of handling command exceptions using ExitStatusExceptionMapper and ExitStatus. This replaces the v3 CommandExceptionResolver.

```java
// v4
public class MyExitStatusExceptionMapper implements ExitStatusExceptionMapper {
	@Override
	public ExitStatus apply(Exception e) {
		// do something with the exception
		return ExitStatus.EXECUTION_ERROR;
	}
}
```

--------------------------------

### FlowComponentSnippets.java - snippet1

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc

Example of a flow using multiple components. The execution order is the same as defined with the builder.

```java
include::{snippets}/FlowComponentSnippets.java[tag=snippet1]
```

--------------------------------

### Status bar ASCII art example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc

Shows the visual appearance of a status bar with items separated by pipes.

```text
┌─────────────────────────────┐
│ Item1 | Item2 | Item3       │
└─────────────────────────────┘
```

--------------------------------

### Run the Spring Shell application

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-samples/spring-shell-sample-spring-boot/README.md

Runs the built Spring Shell application, which starts an interactive command prompt.

```bash
java -jar spring-shell-samples/spring-shell-sample-spring-boot/target/hello-world-boot.jar
```

--------------------------------

### Custom completion provider with @Command and @Bean

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/completion.adoc

This example defines an enum Gender, a command method sayHello with the @Command annotation referencing the completionProvider bean, and a @Bean method that creates a CompositeCompletionProvider combining an EnumCompletionProvider for --gender and a custom nameCompletionProvider that suggests --name=Bob and --name=Alice.

```java
public enum Gender {
	MALE, FEMALE
}

@Command(name = "hello", description = "Say hello to a given name", group = "Greetings",
		help = "A command that greets the user with 'Hello [Mr.|Ms.] ${name}!'. Usage: hello [-n | --name]=<name> [-g | --gender]=<gender>",
		completionProvider = "helloCompletionProvider")
public void sayHello(
		@Option(shortName = 'n', longName = "name", description = "the name of the person to greet", defaultValue = "World") String name,
		@Option(shortName = 'g', longName = "gender", description = "the gender of the person to greet") Gender gender) {
	String prefix = switch (gender) {
		case MALE -> "Mr. ";
		case FEMALE -> "Ms. ";
	};
	System.out.println("Hello " + prefix + name + "!");
}

@Bean
public CompletionProvider helloCompletionProvider() {
	EnumCompletionProvider genderCompletionProvider = new EnumCompletionProvider(Gender.class, "--gender");
	CompletionProvider nameCompletionProvider = completionContext -> List.of(new CompletionProposal("--name=Bob"), new CompletionProposal("--name=Alice"));
	return new CompositeCompletionProvider(nameCompletionProvider, genderCompletionProvider);
}
```

--------------------------------

### JLine style spec color examples

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/appendices/techintro/theming.adoc

Examples of valid color specs: named colors, short formats, and RGB hex formats with x or # prefix.

```text
fg-red
fg-r
fg-rgb:red
fg-rgb:xff3333
fg-rgb:#ff3333
```

--------------------------------

### CommandContextSnippets.java - command-context tag

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/context.adoc

Example showing how to use the CommandContext interface. The snippet is included from the source file using the tag 'command-context'.

```java
include::{snippets}/CommandContextSnippets.java[tag=command-context]
```

--------------------------------

### DialogView ASCII Art Example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/dialog.adoc

Shows the visual structure of a dialog drawn by DialogView, with main content and buttons sections.

```text
┌──────────────────┐
│                  │
│  <Main content>  │
│                  │
├──────────────────┤
│    <Buttons>     │
└──────────────────┘
```

--------------------------------

### PathSearchConfig usage example (Java)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/components/ui/pathsearch.adoc

Shows how to customize the Path Search component using PathSearchConfig. The snippet is included from UiComponentSnippets.java with tag snippet9.

```java
include::{snippets}/UiComponentSnippets.java[tag=snippet9]
```

--------------------------------

### GridView layout result

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/grid.adoc

The resulting layout of the GridView example, showing a 2x2 grid of cells.

```text
┌───┬───┐
│   │   │
│   │   │
├───┼───┤
│   │   │
│   │   │
└───┴───┘
```

--------------------------------

### v3 CommandExceptionResolver example

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Shows the old v3 way of handling command exceptions using CommandExceptionResolver and CommandHandlingResult. This API is replaced in v4 by ExitStatusExceptionMapper.

```java
// v3
class CustomExceptionResolver implements CommandExceptionResolver {

	@Override
	public CommandHandlingResult resolve(Exception e) {
		// do something with the exception
		return CommandHandlingResult.of("EXECUTION_ERROR", -1);;
	}
}
```

--------------------------------

### EventLoop plain events example

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/events/eventloop.adoc

Shows how events are represented as Spring Messages in the EventLoop. This is the basic event handling pattern.

```java
include::{snippets}/EventLoopSnippets.java[tag=plainevents]
```

--------------------------------

### Non-Boot command registration with @EnableCommand

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

When not using Spring Boot, you must use @EnableCommand to enable command discovery. This example shows a standalone Spring context with a ShellRunner to execute commands.

```java
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.shell.core.ShellRunner;
import org.springframework.shell.core.command.annotation.Command;
import org.springframework.shell.core.command.annotation.EnableCommand;
import org.springframework.shell.core.command.annotation.Option;

@EnableCommand(SpringShellApplication.class)
public class SpringShellApplication {

	public static void main(String[] args) throws Exception {
		ApplicationContext context = new AnnotationConfigApplicationContext(SpringShellApplication.class);
		ShellRunner runner = context.getBean(ShellRunner.class);
		runner.run(args);
	}

	@Command
	public void hi() {
		System.out.println("Hello world!");
	}

}
```

--------------------------------

### Add a @Command method to DemoApplication

Source: https://github.com/spring-projects/spring-shell/blob/main/README.adoc

Edit the main application class to add a command method annotated with @Command that returns a greeting. This is the minimal setup for a Spring Shell command.

```java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.shell.core.command.annotation.Command;

@SpringBootApplication
public class DemoApplication {

	@Command
	public String hi() {
		return "hi";
	}

	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}

}
```

--------------------------------

### Command completion with custom CompletionProvider

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

In Spring Shell 4, command completion is centralized at the command level using a custom CompletionProvider. This example shows a command with a completionProvider attribute and a bean that provides completion proposals based on the option being completed.

```java
enum Gender {
	MALE, FEMALE
}

@Command(name = "hello", description = "Say hello to a given name", group = "Greetings",
	help = "A command that greets the user with 'Hello ${name}!'. Usage: hello [-g | --gender]=<gender> [-n | --name]=<name>",
	completionProvider = "helloCompletionProvider")
public void sayHello(
	@Option(shortName = 'n', longName = "name", description = "the name of the person to greet", defaultValue = "World") String name,
	@Option(shortName = 'g', longName = "gender", description = "the gender of the person to greet") Gender gender) {
	String prefix = switch (gender) {
		case MALE -> "Mr. ";
		case FEMALE -> "Ms. ";
	};
	System.out.println("Hello " + prefix + name + "!");
}

@Bean
public CompletionProvider helloCompletionProvider() {
	// if gender is female, suggest "Alice" and "Eve", otherwise suggest "Bob" and "Charlie"
	return completionContext ->
	{
		CommandOption commandOption = completionContext.getCommandOption();
		// check option name and value and return appropriate proposals
		return List.of();
	};
}
```

--------------------------------

### FlowComponentSnippets.java - snippet2

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/components/flow/index.adoc

Example of conditional flow navigation using a 'next' function that returns a target component id. If the id is null or doesn't exist, the flow stops.

```java
include::{snippets}/FlowComponentSnippets.java[tag=snippet2]
```

--------------------------------

### Java: Using @Arguments with arity for multi-valued command arguments

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Shows how to define a command with multi-valued arguments using @Arguments(arity = 2) in Spring Shell v4. The example calculates the real part of the product of two complex numbers, taking two real parts and two imaginary parts as separate arguments. This replaces the previous need to use options for multi-valued input.

```java
@Command(name = "real-part", description = "Calculate the real part of the product of two complex numbers",
		group = "math",
		help = "Calculate the real part of the product of two complex numbers. Example usage: real-part 1 2 3 4")
public double realPartOfComplexProduct(@Arguments(arity = 2) double[] realParts,
		@Arguments(arity = 2) double[] imaginaryParts) {
	return realParts[0] * realParts[1] - imaginaryParts[0] * imaginaryParts[1];
}
```

--------------------------------

### Command availability customization: v3 vs v4

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

In Spring Shell 4, command availability is customized via a single @Command attribute instead of a separate @CommandAvailability annotation. The example shows the v3 and v4 equivalents side by side.

```java
// v3
@Command(name = "download")
@CommandAvailability("loginAvailabilityProvider")
public void downloadCommand() {
    // command implementation
}


// v4
@Command(name = "download", availabilityProvider = "loginAvailabilityProvider")
public void downloadCommand() {
    // command implementation
}
```

--------------------------------

### Spring Boot command registration with automatic scanning

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

In Spring Shell 4, when using Spring Boot, command scanning is automatically enabled, so no explicit annotation like @CommandScan is needed. This example shows a minimal Spring Boot application with a @Command method.

```java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.shell.core.command.annotation.Command;
import org.springframework.shell.core.command.annotation.Option;

@SpringBootApplication
public class SpringShellApplication {

	public static void main(String[] args) {
		SpringApplication.run(SpringShellApplication.class, args);
	}

	@Command
	public void hi() {
		System.out.println("Hello world!");
	}

}
```

--------------------------------

### Defining commands with @Command in a Spring bean

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Example of defining related commands in a Spring-managed bean using @Command on methods. The @Command annotation's command attribute is renamed to name, and methods must be in a Spring-managed bean. This class shares state (loggedIn) between commands.

```java
@Component
public class GitHubCommands {

   private boolean loggedIn = false;
    
   @Command(name = { "github", "auth", "login" }, description = "Login to GitHub", group = "GitHub Authentication Commands")
   public void githubLogin(CommandContext commandContext) {
      PrintWriter writer = commandContext.outputWriter();
      writer.println("Logging in to GitHub...");
      writer.flush();
      // Simulate login process
      this.loggedIn = true;
   }


   @Command(name = { "github", "auth", "logout" }, description = "Logout from GitHub", group = "GitHub Authentication Commands")
   public void githubLogout(CommandContext commandContext) {
      PrintWriter writer = commandContext.outputWriter();
      writer.println("Logging out from GitHub...");
      writer.flush();
      // Simulate logout process
      this.loggedIn = false;
   }
   
}
```

--------------------------------

### Run a sample application with run-sample.sh

Source: https://github.com/spring-projects/spring-shell/blob/main/README.adoc

Launch the convenience script to run any sample from the repository root. The script presents an interactive menu to select a sample.

```bash
$>./run-sample.sh
```

```text
Spring Shell Samples
====================

Select a sample to run:

  1) hello-world       — Simple greeting shell application
  2) non-interactive   — Non-interactive sample (runs 'hi' and exits)
  3) petclinic         — Spring PetClinic shell application
  4) secure-input      — Secure input / password prompt sample
  5) spring-boot       — Spring Boot-based shell application

Enter your choice [1-5]:
```

--------------------------------

### Build the project with Maven

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-samples/spring-shell-sample-hello-world/README.md

Run this command from the project root directory to build the Spring Shell sample project.

```bash
./mvnw clean install
```

--------------------------------

### Run the hello-world application

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-samples/spring-shell-sample-hello-world/README.md

Executes the built JAR file, launching the Spring Shell application and presenting a command prompt.

```bash
java -jar spring-shell-samples/spring-shell-sample-hello-world/target/hello-world.jar
```

--------------------------------

### List all available commands with help

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc

Typing help in the shell lists all known commands along with a short description of their functionality.

```bash
my-shell:>help
Available commands:

Built-In Commands
       clear: Clear the terminal screen
	   help: Show help about available commands
       version: Show version info
```

--------------------------------

### View detailed command information with help <command>

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc

Using the help <command> syntax provides detailed information about a specific command, including its name, synopsis, and available options.

```bash
my-shell:>help version
NAME
	version - Show version info

SYNOPSIS
	version  --help

OPTIONS
	--help or -h
	help for version
	[Optional]
```

--------------------------------

### Test command execution with ShellTestClient

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/testing.adoc

Demonstrates using ShellTestClient to send a command and ShellAssertions to verify the resulting screen output.

```java
@ExtendWith(SpringExtension.class)
class ShellTestClientTests {

	@Test
	void testCommandExecution(@Autowired ShellTestClient shellTestClient) throws Exception {
		// when
		ShellScreen shellScreen = shellTestClient.sendCommand("test");

		// then
		ShellAssertions.assertThat(shellScreen).containsText("Test command executed");
	}
}
```

--------------------------------

### Create a basic ListView

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc

Initializes a basic ListView component.

```java
ListView<String> view = new ListView<>(List.of("Item 1", "Item 2", "Item 3"));
```

--------------------------------

### Run the application in interactive mode

Source: https://github.com/spring-projects/spring-shell/blob/main/README.adoc

Run the built jar in interactive mode and execute the 'help' and 'hi' commands. The output shows the available commands and the result of the 'hi' command.

```bash
$>java -jar target/demo-0.0.1-SNAPSHOT.jar

shell:>help
AVAILABLE COMMANDS

Built-In Commands
	history: Display or save the history of previously run commands
	clear: Clear the terminal screen
	help: Display help about available commands
	quit, exit: Exit the shell
	version: Show version info
	script: Execute commands from a script file
SpringShellApplication Commands
	hi: N/A

shell:>hi
hi
```

--------------------------------

### Build the application with Maven

Source: https://github.com/spring-projects/spring-shell/blob/main/README.adoc

Build the Spring Shell application using Maven, skipping tests.

```bash
$>./mvnw package -DskipTests
```

--------------------------------

### Define a command in SpringShellApplication

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/getting-started.adoc

The main class demonstrating the @EnableCommand and @Command annotations to create a hello command.

```java
@EnableCommand(SpringShellApplication.class)
public class SpringShellApplication {

	public static void main(String[] args) throws Exception {
		ApplicationContext context = new AnnotationConfigApplicationContext(SpringShellApplication.class);
		ShellRunner runner = context.getBean(ShellRunner.class);
		runner.run(args);
	}

	@Command(name = "hello", description = "Say hello to a given name", group = "Greetings",
			help = "A command that greets the user with 'Hello ${name}!'. Usage: hello [-n | --name]=<name>")
	public void sayHello(@Option(shortName = 'n', longName = "name", description = "the name of the person to greet",
			defaultValue = "World") String name) {
		System.out.println("Hello " + name + "!");
	}

}
```

--------------------------------

### Build Spring Shell documentation with Antora

Source: https://github.com/spring-projects/spring-shell/blob/main/README.adoc

Runs the Antora Maven plugin to generate the documentation site for the spring-shell-docs module. After completion, the site is available in spring-shell-docs/target/site.

```bash
$>./mvnw antora -pl spring-shell-docs
```

--------------------------------

### Programmatic availabilityProvider method

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/availability.adoc

Shows how to use the availabilityProvider method with an AvailabilityProvider for programmatic command registration.

```java
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-programmatic]
```

--------------------------------

### Simulate user input with ShellInputProvider

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/testing.adoc

Uses ShellInputProvider to supply custom input to a command during a test.

```java
@Test
void testCommandExecutionWithReadingInput(@Autowired ShellTestClient client) throws Exception {
    // given
    ShellInputProvider inputProvider = ShellInputProvider.providerFor("ask").withInput("hi").build();

    // when
    ShellScreen screen = client.sendCommand(inputProvider);

    // then
    ShellAssertions.assertThat(screen).containsText("You said: hi");
}
```

--------------------------------

### Using PrintWriter from command context

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/writing.adoc

Recommended way to write output in Spring Shell. Obtain a PrintWriter from the command context and use it for writing.

```java
include::{snippets}/WritingSnippets.java[tag=print-writer]
```

--------------------------------

### Create a simple status bar with an item (Java)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc

Creates a simple status bar with a single item using the StatusBarView constructor.

```java
include::{snippets}/StatusBarViewSnippets.java[tag=simple]
```

--------------------------------

### Create a status bar using array-based DSL (Java)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc

Uses the constructor's array form to lay out simple item definitions in a DSL style.

```java
include::{snippets}/StatusBarViewSnippets.java[tag=viaarray]
```

--------------------------------

### Enable native access for FFM

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/building.adoc

JVM option required to enable native access when using FFM. Needed to avoid warnings and potential errors from JLine.

```bash
--enable-native-access=ALL-UNNAMED

```

--------------------------------

### Register ExitStatusExceptionMapper Programmatically with Command.Builder

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/exception-handling.adoc

Builds a command named 'hello' and sets a custom ExitStatusExceptionMapper using the exitStatusExceptionMapper method. The command throws a RuntimeException when the name is '42'.

```java
@Bean
public Command sayHello() {
	return Command.builder()
			.name("hello")
			.description("Say hello to a given name")
			.group("Greetings")
			.help("A command that greets the user with 'Hello ${name}!'. Usage: hello [-n | --name]=<name>")
			.exitStatusExceptionMapper(exception -> new ExitStatus(42, "42! The answer to life, the universe and everything!"))
			.execute(context -> {
				String name = context.getOptionByName("name").value();
				if (name.equals("42")) {
					throw new RuntimeException("Error!");
				}
				System.out.println("Hello " + name + "!");
			});
}
```

--------------------------------

### Define command options and arguments

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

Defines command options and arguments using method parameters. Options are named and can have short and long names, while arguments are positional.

```java
include::{snippets}/CommandAnnotationSnippets.java[tag=command-option-arg]
```

--------------------------------

### Configure ListView selection types

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc

Demonstrates setting the selection mode to NOCHECK, CHECK, or RADIO.

```java
view.setSelectionType(SelectionType.CHECK);
```

--------------------------------

### Configure Gradle bootJar manifest for native access

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/building.adoc

Gradle configuration to add the Enable-Native-Access attribute to the bootJar manifest. Required when using FFM with a jar.

```groovy
tasks.named("bootJar") {
    manifest {
        attributes 'Enable-Native-Access': 'ALL-UNNAMED'
    }
}

```

--------------------------------

### Custom PromptProvider Bean in Spring Boot

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/customization/custom-prompt.adoc

Defines a Spring Boot application with a custom PromptProvider bean that returns an AttributedString with the prompt "myprompt:>" in yellow. The @Command method hi() prints "Hello world!" when invoked.

```java
@SpringBootApplication
static class SpringShellApplication {

	@Command
	public void hi() {
		System.out.println("Hello world!");
	}

	@Bean
	public PromptProvider myPromptProvider() {
		return () -> new AttributedString("myprompt:>", AttributedStyle.DEFAULT.foreground(AttributedStyle.YELLOW));
	}

}
```

--------------------------------

### Use SystemShellRunner with @EnableCommand

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Shows a Spring Shell 4 application using @EnableCommand and the default SystemShellRunner. The main method obtains the ShellRunner bean from the context and runs it. The @Command method 'hi' prints 'Hello world!'.

```java
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.shell.core.ShellRunner;
import org.springframework.shell.core.command.annotation.Command;
import org.springframework.shell.core.command.annotation.EnableCommand;

@EnableCommand(SpringShellApplication.class)
public class SpringShellApplication {

	public static void main(String[] args) throws Exception {
		ApplicationContext context = new AnnotationConfigApplicationContext(SpringShellApplication.class);
		ShellRunner runner = context.getBean(ShellRunner.class);
		runner.run(args);
	}

	@Command
	public void hi() {
		System.out.println("Hello world!");
	}

}
```

--------------------------------

### Status bar items with runnable actions and hot keys (Java)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/statusbar.adoc

Shows how items support runnable actions executed when selected and can be attached to a hot key.

```java
include::{snippets}/StatusBarViewSnippets.java[tag=items]
```

--------------------------------

### AppView layout diagram

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/app.adoc

ASCII diagram showing the typical layout of an AppView with menu, main, and status areas.

```text
┌──────────────────────────┐
│           Menu           │
├──────────────────────────┤
│                          │
│           Main           │
│                          │
├──────────────────────────┤
│          Status          │
└──────────────────────────┘
```

--------------------------------

### Execute script command

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/builtin/script.adoc

Executes a series of commands from a specified script file using the --file option.

```shell
$>script --file /absolute/path/to/your/script.txt
```

--------------------------------

### Run the non-interactive application with 'hi' command

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-samples/spring-shell-sample-non-interactive/README.md

Run this command to execute the jar file and invoke the 'hi' command in non-interactive mode. The result is printed to console and the application exits automatically.

```bash
java -jar spring-shell-samples/spring-shell-sample-non-interactive/target/non-interactive.jar hi
```

--------------------------------

### Group command programmatically with Command.Builder.group(String)

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/organize.adoc

Specifies the group when using the programmatic registration model. The command is built with a name, group, and execution logic.

```java
@Bean
Command myCommand() {
    return Command.builder()
            .name("mycommand")
            .group("My Commands")
            .execute(context -> {
                System.out.println("This is my command!");
            });
}
```

--------------------------------

### Build SearchMatch using builder

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/appendices/techintro/searchalgorithm.adoc

Constructs a SearchMatch instance using its builder. The builder is package protected, so this is the required way to create a SearchMatch.

```java
include::{snippets}/SearchAlgorithmsSnippets.java[tag=builder]
```

--------------------------------

### Execute the Spring Shell application

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/getting-started.adoc

Command to run the SpringShellApplication class using the Maven exec plugin.

```shell
./mvnw -pl org.springframework.shell:spring-shell-sample-hello-world exec:java -Dexec.mainClass=org.springframework.shell.samples.helloworld.SpringShellApplication
```

--------------------------------

### Gradle native plugin and metadata repository configuration

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/building.adoc

Gradle build configuration to use GraalVM native plugin and enable the metadata repository. Required for native compilation.

```groovy
plugins {
	id 'org.graalvm.buildtools.native' version '0.9.16'
}

graalvmNative {
	metadataRepository {
        enabled = true
	}
}

```

--------------------------------

### Default ProgressView usage

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/progress.adoc

Shows the default ProgressView with text, spinner, and percent items. The output is displayed in an asciinema recording.

```java
include::{snippets}/ProgressViewSnippets.java[tag=default]
```

--------------------------------

### Configure native-maven-plugin metadata repository in Maven build

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/building.adoc

Add this pluginManagement configuration to enable the GraalVM metadata repository for the native-maven-plugin. If you use spring-boot-starter-parent, the plugin version is managed automatically and kept up to date.

```xml
<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.graalvm.buildtools</groupId>
                <artifactId>native-maven-plugin</artifactId>
                <configuration>
                    <metadataRepository>
                        <enabled>true</enabled>
                    </metadataRepository>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
```

--------------------------------

### Command grouping: v3 @Command vs v4 @CommandGroup

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Comparison of v3 and v4 command grouping. In v3, @Command on a class groups commands; in v4, use @CommandGroup with prefix and name attributes, and @Command only on methods.

```java
//v3
@Command(command = "github auth", group = "Github Authentication Commands")
public class GitHubCommands {

    @Command(command = "login", description = "Login to GitHub.")
    public void login() {
        // ...
    }

    @Command(command = "logout", description = "Logout from GitHub.")
    public void logout() {
        // ...
    }
    
}
```

```java
//v4
@CommandGroup(prefix = "github auth", name = "Github Authentication Commands")
public class GitHubCommands {

    @Command(name = "login", description = "Login to GitHub.")
    public void login() {
        // ...
    }

    @Command(name = "logout", description = "Logout from GitHub.")
    public void logout() {
        // ...
    }
    
}
```

--------------------------------

### Command syntax grammar

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

Grammar for Spring Shell command syntax. Options can be long form (--key=value or --key value) or short form (-k=value or -k value). Options and arguments can be in any order.

```shell
CommandSyntax  ::= CommandName [SubCommandName]* [Option | Argument]*
CommandName    ::= String
SubCommandName ::= String
Option         ::= ShortOption | LongOption
ShortOption    ::= '-' Char ['='|' ']? String
LongOption     ::= '--' String ['='|' ']? String
Argument       ::= String
```

--------------------------------

### Integration testing with @ShellTest

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/testing.adoc

Shows how to use the @ShellTest annotation to configure a test context for a Spring Boot shell application, including testing for command execution and command not found exceptions.

```java
@SpringBootApplication
public class ExampleShellApplication {

	@Command(name = "hi", description = "Says hello")
	public String hello() {
		return "hello";
	}

}

@ShellTest
@ContextConfiguration(classes = ExampleShellApplication.class)
class ShellTestIntegrationTests {

	@Test
	void testCommandExecution(@Autowired ShellTestClient client) throws Exception {
		// when
		ShellScreen shellScreen = client.sendCommand("hi");

		// then
		ShellAssertions.assertThat(shellScreen).containsText("hello");
	}

	@Test
	void testUnknownCommandExecution(@Autowired ShellTestClient client) {
		Assertions.assertThatThrownBy(() -> client.sendCommand("foo"))
                  .isInstanceOf(CommandNotFoundException.class);
	}

}
```

--------------------------------

### MenuBarView visual representation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/menubar.adoc

A text-based representation of how a MenuBarView appears.

```text
┌─────────────────────────────┐
│ File Help                   │
└─────────────────────────────┘
```

--------------------------------

### End-to-end testing with @SpringBootTest

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/testing.adoc

Performs black-box testing of a shell application using @SpringBootTest and OutputCaptureExtension to verify console output.

```java
@SpringBootApplication
public class MyShellApplication {

	public static void main(String[] args) {
		SpringApplication.run(MyShellApplication.class, args);
	}

	@Command
	public void hi() {
		System.out.println("Hello world!");
	}

}

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE,
		useMainMethod = SpringBootTest.UseMainMethod.ALWAYS,
		classes = { MyShellApplication.class },
		properties = { "spring.shell.interactive.enabled=false" },
        args = "hi")
@ExtendWith(OutputCaptureExtension.class)
public class ShellApplicationEndToEndTests {

	@Test
	void testCommandOutput(CapturedOutput output) {
		assertThat(output).contains("Hello world!");
	}

}
```

--------------------------------

### BoxView drawFunction usage

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/box.adoc

Shows how to use BoxView's drawFunction to draw simple content without implementing a full custom View. The snippet is included from BoxViewSnippets.java with tag 'sample'.

```java
include::{snippets}/BoxViewSnippets.java[tag=sample]
```

--------------------------------

### Enable-Native-Access manifest attribute

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/building.adoc

Manifest attribute for jar files to enable native access. Can be added during build using Gradle.

```text
Enable-Native-Access: ALL-UNNAMED

```

--------------------------------

### Annotation availabilityProvider attribute

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/availability.adoc

Shows how to use the availabilityProvider attribute to specify the name of the AvailabilityProvider bean for annotation-based commands.

```java
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-annotation]
```

--------------------------------

### Implement a custom CellFactory

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc

Defines a custom CellFactory to control how individual list items are rendered.

```java
CellFactory<String> factory = (item) -> Label.of("Item: " + item);
```

--------------------------------

### Subscribe to all key events in Java

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/events/key.adoc

Subscribe to all key events in a Spring Shell TUI view. The KeyEvent record contains information about a binding coming from a terminal.

```java
include::{snippets}/KeyHandlingSnippets.java[tag=sample]
```

--------------------------------

### Confirmation component snippet include

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/components/ui/confirmation.adoc

The source uses an include directive to reference the code snippet from UiComponentSnippets.java. The actual code is not displayed on this page.

```java
include::{snippets}/UiComponentSnippets.java[tag=snippet5]
```

--------------------------------

### Observe validation error output

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/validation.adoc

Shows the error message generated when the provided password fails the @Size constraint.

```bash
$>change-password --password=hello
The following constraints were not met:
	--password: size must be between 8 and 40
Error while executing command change-password: USAGE_ERROR
```

--------------------------------

### ButtonView visual representation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/button.adoc

The visual structure of a ButtonView component.

```text
┌──────┐
│ text │
└──────┘
```

--------------------------------

### Custom ProgressView with mixed alignment and size

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/progress.adoc

Customizes the ProgressView by aligning text and spinner to the left with less space, and percent to the right with remaining space. The output is shown in an asciinema recording.

```java
include::{snippets}/ProgressViewSnippets.java[tag=allmixedalignandsize]
```

--------------------------------

### Define a programmatic command with Command.Builder

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Creates a Command bean named 'mycommand' that prints a message when executed. Any bean of type Command is automatically registered as a command in Spring Shell 4.

```java
@Bean
public Command myCommand() {
	return Command.builder().name("mycommand").execute(context -> {
		context.outputWriter().println("This is my command!");
	});
}
```

--------------------------------

### Group commands at class level with @CommandGroup

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/organize.adoc

Defines a group and prefix for all commands in a class. Commands in the class share the group and can be invoked with the prefix (e.g., 'auth login'). The group attribute on a command overrides the class-level group.

```java
@CommandGroup(name = "Authentication Commands", prefix = "auth")
public class AuthenticationCommands {

	private boolean authenticated = false;

	@Command(name = "login", description = "Log in to the system")
	public void login() {
        // Authentication logic here
        authenticated = true;
        System.out.println("Logged in successfully!");
    }

    @Command(name = "logout", description = "Log out of the system")
    public void logout() {
        // Logout logic here
        authenticated = false;
        System.out.println("Logged out successfully!");
    }
}
```

--------------------------------

### Apply a custom CellFactory to ListView

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/views/list.adoc

Sets the custom CellFactory on the ListView instance.

```java
view.setCellFactory(factory);
```

--------------------------------

### Define command with @Size validation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/validation.adoc

Uses the @Size annotation on a command parameter to enforce length constraints on the password option.

```java
@Command(name = "change-password", description = "Change password", group = "User Management",
		help = "A command that changes the user password. Usage: change-password [-p | --password]=<password>")
public String changePassword(
		@Option(shortName = 'p', longName = "password") @Size(min = 8, max = 40) String password) {
	return "Password successfully set to " + password;
}
```

--------------------------------

### Unsupported @Command on top-level class

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Shows the unsupported usage of @Command on a top-level class in v4. This pattern is no longer allowed; the @Command annotation can only be used on methods.

```java
@Command
class Example {

    @Command(command = "example")
    public String example() {
        return "Hello";
    }
}
```

--------------------------------

### Define multi-valued arguments with @Arguments

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

Defines multi-valued arguments using the @Arguments annotation on an array or collection type. All remaining command line tokens are collected into the collection.

```java
include::{snippets}/CommandAnnotationSnippets.java[tag=multi-valued-argument]
```

--------------------------------

### Subscribe to all mouse events in Java

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/tui/events/mouse.adoc

Use this snippet to subscribe to all mouse events in a Spring Shell TUI application. The MouseEvent is a record wrapping X and Y coordinates and the org.jline.terminal.MouseEvent from the JLine library.

```java
include::{snippets}/MouseHandlingSnippets.java[tag=sample]
```

--------------------------------

### Register ExitStatusExceptionMapper via @Command Annotation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/exception-handling.adoc

Shows annotation-based registration: the @Command annotation references the custom mapper bean by name 'myCustomExceptionMapper'. The command method throws a RuntimeException when the name is '42'. The mapper bean must be defined as a Spring bean.

```java
@Command(name = "hello", description = "Say hello to a given name", group = "Greetings",
		help = "A command that greets the user with 'Hello ${name}!'. Usage: hello [-n | --name]=<name>",
		exitStatusExceptionMapper = "myCustomExceptionMapper")
public void sayHello(@Option(shortName = 'n', longName = "name", description = "the name of the person to greet",
		defaultValue = "World") String name) {
	if (name.equals("42")) {
		throw new RuntimeException("Error!");
	}
	System.out.println("Hello " + name + "!");
}

@Bean
public ExitStatusExceptionMapper myCustomExceptionMapper() {
	return exception -> new ExitStatus(42, "42! The answer to life, the universe and everything!");
}
```

--------------------------------

### Configure spring.shell.context.close to true in YAML

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/customization/contextclose.adoc

Set the configuration property spring.shell.context.close to true to register an ApplicationListener for ApplicationReadyEvent and request context close after shell execution. This setting is not enabled by default.

```yaml
spring:
  shell:
    context:
      close: true

```

--------------------------------

### Define multi-valued arguments with arity

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

Uses the arity attribute of @Arguments to specify the number of arguments to collect. By default, arity is not bound, collecting all remaining tokens.

```java
include::{snippets}/CommandAnnotationSnippets.java[tag=multi-valued-argument-with-arity]
```

--------------------------------

### Command interface with execute method in Spring Shell 4

Source: https://github.com/spring-projects/spring-shell/wiki/v4-migration-guide

Defines the new Command contract in Spring Shell 4. It is a functional interface with a single execute method that takes a CommandContext and returns an ExitStatus. Exceptions thrown during execution are propagated by default unless customized via an ExitStatusExceptionMapper.

```java
@FunctionalInterface
public interface Command {

   /**
    * Execute the command within the given context.
    * @param commandContext the context of the command
    * @return the exit status of the command
    * @throws Exception if an error occurs during command execution
    */
   ExitStatus execute(CommandContext commandContext) throws Exception;

}
```

--------------------------------

### Group command with @Command annotation

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/organize.adoc

Sets the group for a single command using the group attribute in @Command. The command will appear under the specified group in the help screen.

```java
@Command(name = "example", group = "My Commands")
public String example() {
    return "Hello";
}
```

--------------------------------

### Implement ExitStatusExceptionMapper as a Spring Bean

Source: https://github.com/spring-projects/spring-shell/blob/main/spring-shell-docs/modules/ROOT/pages/commands/exception-handling.adoc

Defines a custom ExitStatusExceptionMapper bean that returns an ExitStatus with code 42 and a message. The mapper is a functional interface taking an Exception and returning an ExitStatus.

```java
@Bean
public ExitStatusExceptionMapper myCustomExceptionMapper() {
	return exception -> new ExitStatus(42, "42! The answer to life, the universe and everything!");
}
```
Tokens:
Raw