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