spring-shell

What this skill does

# Spring Shell - Quick Reference

> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `spring-shell` for comprehensive documentation.

## Dependencies

```xml
<dependency>
    <groupId>org.springframework.shell</groupId>
    <artifactId>spring-shell-starter</artifactId>
</dependency>
```

## Configuration

### application.yml
```yaml
spring:
  shell:
    interactive:
      enabled: true
    noninteractive:
      enabled: true
    history:
      enabled: true
      name: .myapp_history
    command:
      version:
        enabled: true
```

## Basic Commands

### Simple Command
```java
@ShellComponent
public class GreetingCommands {

    @ShellMethod(value = "Say hello", key = "hello")
    public String hello(
            @ShellOption(defaultValue = "World") String name) {
        return "Hello, " + name + "!";
    }

    @ShellMethod("Add two numbers")
    public int add(int a, int b) {
        return a + b;
    }

    @ShellMethod("Show current date")
    public String date() {
        return LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}
```

### Command Groups
```java
@ShellComponent
@ShellCommandGroup("User Management")
public class UserCommands {

    @ShellMethod("List all users")
    public Table listUsers() {
        List<User> users = userService.findAll();
        return buildUserTable(users);
    }

    @ShellMethod("Create a new user")
    public String createUser(
            @ShellOption(help = "Username") String username,
            @ShellOption(help = "Email address") String email,
            @ShellOption(help = "User role", defaultValue = "USER") String role) {

        User user = userService.create(username, email, role);
        return "Created user: " + user.getId();
    }

    @ShellMethod("Delete a user")
    public String deleteUser(@ShellOption(help = "User ID") Long id) {
        userService.delete(id);
        return "User deleted successfully";
    }
}
```

## Shell Options

### Option Annotations
```java
@ShellComponent
public class AdvancedCommands {

    @ShellMethod("Process file with options")
    public String process(
            // Required option
            @ShellOption(help = "Input file path") String input,

            // Optional with default
            @ShellOption(defaultValue = "output.txt", help = "Output file") String output,

            // Boolean flag
            @ShellOption(defaultValue = "false", help = "Verbose mode") boolean verbose,

            // Array/List option
            @ShellOption(help = "Tags to apply") String[] tags,

            // Arity (number of values)
            @ShellOption(arity = 2, help = "Coordinates x y") int[] coords) {

        // Implementation
        return "Processing " + input;
    }

    // Named options with aliases
    @ShellMethod("Export data")
    public String export(
            @ShellOption(value = {"-f", "--format"}, defaultValue = "json") String format,
            @ShellOption(value = {"-o", "--output"}) String output,
            @ShellOption(value = {"-c", "--compress"}, defaultValue = "false") boolean compress) {

        return String.format("Exporting to %s in %s format (compressed: %s)",
            output, format, compress);
    }
}
```

## Availability and Validation

### Command Availability
```java
@ShellComponent
public class AdminCommands {

    private boolean authenticated = false;

    @ShellMethod("Login to the system")
    public String login(String username, String password) {
        if (authService.authenticate(username, password)) {
            authenticated = true;
            return "Login successful";
        }
        return "Login failed";
    }

    @ShellMethod("Perform admin action")
    @ShellMethodAvailability("isAuthenticated")
    public String adminAction() {
        return "Admin action performed";
    }

    public Availability isAuthenticated() {
        return authenticated
            ? Availability.available()
            : Availability.unavailable("You must login first");
    }

    // Apply to multiple methods
    @ShellMethodAvailability({"adminAction", "deleteAll", "resetSystem"})
    public Availability requiresAdmin() {
        return currentUser.isAdmin()
            ? Availability.available()
            : Availability.unavailable("Admin privileges required");
    }
}
```

### Input Validation
```java
@ShellComponent
public class ValidatedCommands {

    @ShellMethod("Create user with validation")
    public String createUser(
            @ShellOption @Size(min = 3, max = 20) String username,
            @ShellOption @Email String email,
            @ShellOption @Min(18) @Max(120) int age) {

        return "User created: " + username;
    }
}

// Custom validator
@Component
public class FileExistsValidator implements Validator {

    @Override
    public boolean supports(Class<?> clazz) {
        return String.class.isAssignableFrom(clazz);
    }

    @Override
    public void validate(Object target, Errors errors) {
        String path = (String) target;
        if (!Files.exists(Path.of(path))) {
            errors.reject("file.notfound", "File does not exist: " + path);
        }
    }
}
```

## Output Formatting

### Tables
```java
@ShellComponent
public class TableCommands {

    @ShellMethod("Show users in table format")
    public Table showUsers() {
        List<User> users = userService.findAll();

        TableModel model = new BeanListTableModel<>(users,
            new LinkedHashMap<>() {{
                put("id", "ID");
                put("username", "Username");
                put("email", "Email");
                put("role", "Role");
                put("createdAt", "Created");
            }});

        TableBuilder tableBuilder = new TableBuilder(model);
        tableBuilder.addFullBorder(BorderStyle.fancy_light);
        return tableBuilder.build();
    }

    // Custom table
    @ShellMethod("Show system info")
    public Table systemInfo() {
        String[][] data = {
            {"OS", System.getProperty("os.name")},
            {"Java", System.getProperty("java.version")},
            {"Memory", Runtime.getRuntime().maxMemory() / 1024 / 1024 + " MB"},
            {"Processors", String.valueOf(Runtime.getRuntime().availableProcessors())}
        };

        TableModel model = new ArrayTableModel(data);
        TableBuilder builder = new TableBuilder(model);
        builder.addHeaderBorder(BorderStyle.fancy_double);
        return builder.build();
    }
}
```

### Colored Output
```java
@ShellComponent
public class ColoredCommands {

    @ShellMethod("Show status with colors")
    public AttributedString status() {
        AttributedStringBuilder builder = new AttributedStringBuilder();

        builder.append("Status: ");
        builder.style(AttributedStyle.DEFAULT.foreground(AttributedStyle.GREEN));
        builder.append("RUNNING");
        builder.style(AttributedStyle.DEFAULT);
        builder.append("\n");

        builder.append("Errors: ");
        builder.style(AttributedStyle.DEFAULT.foreground(AttributedStyle.RED).bold());
        builder.append("3");
        builder.style(AttributedStyle.DEFAULT);

        return builder.toAttributedString();
    }
}
```

## Interactive Input

### User Prompts
```java
@ShellComponent
public class InteractiveCommands {

    private final LineReader lineReader;

    @ShellMethod("Interactive user creation")
    public String createUserInteractive() {
        String username = lineReader.readLine("Enter username: ");
        String email = lineReader.readLine("Enter email: ");
        String password = lineReader.readLine("Enter password: ", '*');

        String confirm = lineReader.readLine("Create user? (y/n): ");
        if ("y".equalsIgnoreCase(confirm)) {
            userService.create(username, email, password);
            return "User created successfully";
        }
        return "Cancelled";
    }
}
```

### Progress Indicators
```java
@ShellComponent
public class Progr