Spring Shell - Quick Reference

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

Dependencies

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

Configuration

application.yml

spring: shell: interactive: enabled: true noninteractive: enabled: true history: enabled: true name: .myapp_history command: version: enabled: true

Basic Commands

Simple Command

@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

@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

@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

@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

@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

@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

@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

@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

@ShellComponent public class ProgressCommands {

private final TerminalUI terminalUI;

@ShellMethod("Import data with progress")
public void importData(String file) throws Exception {
    List<String> lines = Files.readAllLines(Path.of(file));
    int total = lines.size();

    try (ProgressView progress = terminalUI.progressView()
            .spinner(Spinner.SIMPLE)
            .text("Importing data...")
            .max(total)
            .start()) {

        for (int i = 0; i < total; i++) {
            processLine(lines.get(i));
            progress.setValue(i + 1);
            progress.setText("Processing " + (i + 1) + "/" + total);
        }
    }
}

}

Non-Interactive Mode

// Run single command // java -jar myapp.jar hello --name John

// Run script // java -jar myapp.jar @commands.txt

@SpringBootApplication public class CliApplication implements CommandLineRunner {

@Autowired
private Shell shell;

@Override
public void run(String... args) throws Exception {
    if (args.length > 0 && args[0].equals("--batch")) {
        // Run in non-interactive mode
        shell.evaluate(() -> "process-batch --file data.csv");
        shell.evaluate(() -> "export --format json --output result.json");
        System.exit(0);
    }
    // Otherwise, start interactive shell
}

}

Custom Prompt

@Component public class CustomPromptProvider implements PromptProvider {

private String currentContext = "default";

@Override
public AttributedString getPrompt() {
    return new AttributedString(
        String.format("myapp:%s> ", currentContext),
        AttributedStyle.DEFAULT.foreground(AttributedStyle.CYAN)
    );
}

public void setContext(String context) {
    this.currentContext = context;
}

}

Exception Handling

@Component public class CustomExceptionHandler implements CommandExceptionResolver {

@Override
public CommandHandlingResult resolve(Exception ex) {
    if (ex instanceof IllegalArgumentException) {
        return CommandHandlingResult.of(
            "Invalid argument: " + ex.getMessage() + "\n",
            1  // Exit code
        );
    }
    if (ex instanceof ResourceNotFoundException) {
        return CommandHandlingResult.of(
            "Error: " + ex.getMessage() + "\n",
            2
        );
    }
    // Let default handler process
    return null;
}

}

Testing

@SpringBootTest class CommandsTest {

@Autowired
private Shell shell;

@Test
void shouldSayHello() {
    Object result = shell.evaluate(() -> "hello --name John");
    assertThat(result).isEqualTo("Hello, John!");
}

@Test
void shouldAddNumbers() {
    Object result = shell.evaluate(() -> "add 5 3");
    assertThat(result).isEqualTo(8);
}

@Test
void shouldShowUnavailableForAdminCommands() {
    Object result = shell.evaluate(() -> "admin-action");
    assertThat(result.toString()).contains("must login first");
}

}

Best Practices

Do Don't

Group related commands Create flat command structure

Provide --help for all options Leave options undocumented

Use tables for structured data Dump raw data

Implement availability checks Let commands fail cryptically

Support both interactive and batch Force one mode only

Production Checklist

• Commands grouped logically

• All options documented (help)

• Input validation implemented

• Proper error handling

• Progress indicators for long ops

• Non-interactive mode supported

• Exit codes defined

• History enabled/configured

• Security checks (authentication)

• Tab completion working

When NOT to Use This Skill

• Simple scripts - Use regular main method

• Batch processing - Use spring-batch skill

• Web APIs - Use spring-rest skill

• GUI applications - Consider JavaFX

Anti-Patterns

Anti-Pattern Problem Solution

Flat command structure Hard to navigate Group related commands

Undocumented options Poor UX Add help to all options

No availability checks Cryptic failures Implement @ShellMethodAvailability

Raw data output Unreadable Use tables for structured data

Interactive-only mode Not scriptable Support batch mode

Quick Troubleshooting

Problem Diagnostic Fix

Command not found Check annotation Add @ShellComponent

Option not recognized Check naming Verify @ShellOption config

Validation not working Check annotations Add Bean Validation

Command unavailable Check availability Verify availability method

Tab completion missing Check setup Configure completion bean

Reference Documentation

• Spring Shell Reference