Trouble with 4.0.0

[gturner834]

Brief description of our projects:

Originally:

• A dozen projects we call batch modules that perform ETL (Extract, Transform, Load) operations on huge data sets.
• A common jar library that contains JPA entities, DAO's, and utility methods for dealing with Google BigQuery, Cloud
  Storage, custom Airflow integration, etc.
• Each project builds an executable jar, barely has any frameworks other than Google Guice, and manually bootstraps an
  outdated version of Hibernate.
• Command-line parsing based on Apache commons-cli.

Goal:

• Switch to Spring ecosystem: Spring Data JPA, Spring Batch, Spring Shell.
• Switch from Java to Kotlin.
• Given the hurdle that our developers face with the complex command lines, unique to each project, having Spring Shell's
  interactive mode (completion, help, history, colored output, etc.) is really great!

Progress:

• Sufficient progress, near production readiness.
• Spring Boot 4 dropped a month ago, only difficulty with upgrading were the Spring Batch changes.
• Spring Boot 4 mixed with Spring Shell 3.4.1 didn't seem to present any issues.
• Spring Shell 4.0.0-M1 upgrade was trivial.
• Spring Shell 4.0.0 version released this week caused major breakage.

Issues with 4.0.0

1. Interactive and non-interactive modes are now mutually exclusive.

   • Under 3.4.1, with property spring.shell.interactive.enabled = true, running the jar with any arguments automatically engaged non-interactive behavior, giving best of both worlds: without arguments = interactive, with arguments = non-interactive.

2. @CommandScan was removed and the replacement CommandRegistryAutoConfiguration which only scans from the
   @SpringBootApplication declaring package.

   • We have several commands defined in different packages imported from our utility jars (e.g. "gcs download", "batch
     list").
   • Fix is to create our own @RegisteredCommand annotation and add some startup code that mimics the behavior of
     registerAnnotatedCommands.

     @MustBeDocumented
     @Target(CLASS)
     @Retention(RUNTIME)
     @Component
     annotation class RegisteredCommand
     
     @Configuration
     class CommandRegistrationConfig(
         private val context: ApplicationContext,
         private val commandRegistry: CommandRegistry
     ) {
      
          @PostConstruct
          fun registerCommands() {
              val beanNames = context.getBeanNamesForAnnotation(RegisteredCommand::class.java)
              for (beanName in beanNames) {
                  val beanType = context.getType(beanName) ?: continue
                  val methods = MethodIntrospector.selectMethods(beanType) {
                      AnnotatedElementUtils.hasAnnotation(it, Command::class.java)
                  }
                  for (method in methods) {
                      val factoryBean = CommandFactoryBean(method)
                      factoryBean.setApplicationContext(context)
                      commandRegistry.registerCommand(factoryBean.getObject())
                  }
              }
          }
     
      }

3. @OptionValues was removed, replaced with @Command-level declaration, causing a lot of boilerplate.

   • Two common examples we have are --periodCd YYYYMM and --jobName (Spring Batch Job bean name) that appear on dozens of commands.
   • 3.4.1:

     @Command(
         command = ["restart"],
         description = "Restart a job"
     )
     fun restart(
         @Option(
             longNames = ["jobName"],
             shortNames = ['j'],
             required = false,
             description = "Name of the job to restart",
             label = "JOB_NAME",
             arity = ZERO_OR_ONE
         )
         @OptionValues(provider = [JobNameCompletionProvider.BEAN_NAME])
         jobName: String? = null,
     ) {}

   • 4.0.0:

     @Command(
         name = ["batch restart"],
         description = "Restart a job",
         completionProvider = "batchCommandRestartCompletionProvider"
     )
     fun restart(
         @Option(
             shortName = 'j',
             longName = "jobName",
             description = "Name of the job to restart",
         )
         jobName: String? = null,
     ) {}
     
     @Bean
     fun batchCommandRestartCompletionProvider(): CompositeCompletionProvider {
         TODO("Need to build one of these for every command, with hard-coded parameter names")
     }

   • In addition, using @OptionValues with no provider on enums was working great before, and will now have to construct EnumCompletionProvider for each command.

4. @Command is no longer applicable to classes (methods only), hierarchy/sub-commands no longer supported.

   • 3.4.1:

     @Command(command = ["cm"], group = "Certification Module")
     class CertificationCommand {
     
         @Command(
             command = ["certify"],
             description = "Certify a cost allocation period and launch GBQ and MAAP processes"
         )
         fun certify() {}
     
         // Additional commands...
     
     }

   • 4.0.0:

     class CertificationCommand {
     
         @Command(
            name = ["$COMMAND_PREFIX certify"], // Boilerplate prefix on every command
            group = COMMAND_GROUP, // Boilerplate group on every command
            description = "Certify a cost allocation period and launch GBQ and MAAP processes"
         )
         fun certify() {}
     
         // Additional commands...
     
         companion object {
             private const val COMMAND_GROUP = "Certification"
             private const val COMMAND_PREFIX = "cm"
         }
     
      }

5. Optional parameters spam warning messages.

   2026-01-01T16:06:24.121-08:00  WARN 13500 --- [certification-module] [           main] o.s.s.c.c.a.MethodInvokerCommandAdapter  : No value provided for optional option '--periodCd' and no default value specified.
   

6. @Option no longer supports alternative/alias longNames (array vs. single value).

7. Exception handling in interactive mode does not report cause, and stacktrace command no longer exists.

   • 3.4.1:

     shell:>cm certify --certificationDate 2025-11-18
     COSN021-003E:Period code is required, specified by either "cm certify --periodCd" or "xme config --periodCode" commands(srcApplicationId:CostAllocationApp)(correlationId:fc1063dc-32c5-424f-9687-033cba8cbfc7)
     Details of the error have been omitted. You can use the stacktrace command to print the full stacktrace.
     

     • This exception was intentional, displayed perfectly in red color, and with working stacktrace command.
   • 4.0.0:

     shell:>cm certify --certificationDate 2025-11-18
     Unable to run command cm: null
     shell:>stacktrace
     Command stacktrace not found
     

     • The "null" message comes Shell not looking at the root cause of the TargetInvocationException.
     • The message is printed without color.
     • Also note the truncated command name "cm" instead of "cm certify".

8. Regression with help

   • No longer displays help for individual commands, only has top-level list of commands.
   • 3.4.1:

     shell:>help cm certify
     NAME
         cm certify - Certify a cost allocation period and launch GBQ and MAAP processes
     
     SYNOPSIS
         cm certify [--certificationDate DATE] [--certifiedBy NAME] [--certifiedByEmail EMAIL] --periodCd YYYYMM --insertRecord BOOLEAN --launchGBQ BOOLEAN --launchMAAP BOOLEAN --sequenceName SEQUENCE --sequenceContinuation BOOLEAN --help
     
     OPTIONS
         --certificationDate or --certifiedDate or --date or -d DATE
         Date that the cost allocation period was certified
         [Mandatory]
     …
     

   • 4.0.0:

     shell:>help cm certify
     Command help cm certify not found
     

9. @Option has removed label property pertaining to help (e.g. see DATE, NAME, EMAIL, etc. in 3.4 example above).

10. Regression with version

• We were issuing this command as part of a script for the purpose of printing build information in our Airflow logs (people liked it, "Look what Spring Shell does out of the box!").
• 3.4.1:

  shell:>version
  Build Version: 5.0.0-SNAPSHOT
  Build Group: com.xpo.ltl.java.util
  Build Artifact: ltl-java-costallocation-certification-module
  Build Name: certification-module
  Build Time: 2025-12-01T23:10:18.233Z
  

• 4.0.0:

  shell:>version
  Version: 4.0.0
  

  • Suggestion: print "Spring Shell Version: 4.0.0".

11. The @ShellTest overhaul looks like it'll be helpful, but I'm still working through the above issues, unable to execute tests just yet...

• Outdated test for 3.4.1 that's probably doomed since it's interactive and command-less:

  @ShellTest
  // @ShellTest disables auto-configuration, re-enable it:
  @OverrideAutoConfiguration(enabled = true)
  // @ShellTest filters excluding anything but @ShellComponent, we need all our
  //   components for integration testing:
  @TypeExcludeFilters
  @ContextConfiguration(classes = [TestApplication::class])
  @TestPropertySource(
      properties = [
          "xpo.shell.terminal.rate-limits.warning.limits[0].capacity = 2",
          "xpo.shell.terminal.rate-limits.warning.limits[0].tokens = 1"
      ]
  )
  class TerminalServiceTest(
      val client: ShellTestClient,
      val terminalService: TerminalService
  ) {
  
      @Test
      fun `Should rate limit`() {
          val session = client.interactive().run()
  
          terminalService.printWarn { "First" }
          terminalService.printWarn { "Second" }
          terminalService.printWarn { "Third" }
          terminalService.printWarn { "Fourth" }
          terminalService.printWarn { "Fifth" }
  
          await().atMost(3.seconds.toJavaDuration()).untilAsserted {
              assertThat(session.screen())
                  .containsText("First")
                  .containsText("Second")
                  .containsText("Suppressed messages that are being written too quickly")
                  .doesNotContainText("Third", "Fourth", "Fifth")
          }
      }
  
      companion object {
  
          /**
           * Verifies that the actual [ShellScreen] does not contain any of the
           * given values.
           */
          fun ShellScreenAssert.doesNotContainText(
              vararg values: String
          ): ShellScreenAssert {
              assertThat(this.actual().lines().joinToString("\n"))
                  .doesNotContain(*values)
              return this
          }
  
      }
  
  }

• Another outdated test for 3.4.1 that should be simplified in 4.0.0:

  @ShellTest
  // @ShellTest disables auto-configuration, re-enable it:
  @OverrideAutoConfiguration(enabled = true)
  // @ShellTest filters excluding anything but @ShellComponent, we need all our
  //   components for integration testing:
  @TypeExcludeFilters
  @ContextConfiguration(
  classes = [
      TestApplication::class,
      XmeCommandTest.Config::class
  ]
  )
  // @CommandScan does not work with @ShellTest, must specify commands that are
  //   being tested:
  @EnableCommand(XmeCommand::class)
  @DirtiesContext(classMode = AFTER_EACH_TEST_METHOD)
  class XmeCommandTest(
      val client: ShellTestClient,
      val exceptionResolver: ExceptionResolver
  ) {
  
      @Test
      fun `xme config should display and modify parameters`() {
          val session = client.interactive().run()
  
          // 1. Wait for prompt
  
          await().atMost(3.seconds.toJavaDuration()).untilAsserted {
              // Fail-fast if an exception was observed (it's only fast because
              //   `untilAsserted` is retrying on AssertionError's, other
              //   exception types will abort the loop and rethrow)
              exceptionResolver.check()
  
              assertThat(session.screen()).containsText("shell:>")
          }
  
          // 2. Run `xme config` without options, displaying current parameters
  
          session.write(session.writeSequence().command("xme config").build())
  
          await().atMost(3.seconds.toJavaDuration()).untilAsserted {
              // Fail-fast if an exception was observed
              exceptionResolver.check()
  
              assertThat(session.screen())
                  .containsTextIgnoringWhitespaces(
                      """
                          Module configuration parameters: {
                            "moduleInstId" : null,
                            "moduleVersionSequenceNbr" : null,
                            "moduleGroupInstId" : null,
                            "moduleGroupModuleVersionSequenceNbr" : null,
                            "executionDateTime" : null,
                            "resourcePath" : null,
                            "bucketLocation" : null,
                            "bucketFolder" : null,
                            "periodCode" : null
                          }
                      """.trimIndent()
                  )
          }
  
          // 3. Run `xme config` with options to modify parameters
  
          session.write(
              session
                  .writeSequence()
                  .command(
                      """
                          xme config \
                            --moduleGroupInstId 305 \
                            --periodCode 202510
                      """.trimIndent()
                  )
                  .build()
          )
  
          await().atMost(3.seconds.toJavaDuration()).untilAsserted {
              exceptionResolver.check()
  
              assertThat(session.screen())
                  .containsTextIgnoringWhitespaces(
                      """
                          Module configuration parameters: {
                            "moduleInstId" : null,
                            "moduleVersionSequenceNbr" : null,
                            "moduleGroupInstId" : 305,
                            "moduleGroupModuleVersionSequenceNbr" : null,
                            "executionDateTime" : null,
                            "resourcePath" : null,
                            "bucketLocation" : null,
                            "bucketFolder" : null,
                            "periodCode" : 202510
                          }
                      """.trimIndent()
                  )
          }
      }
  
      companion object {
  
          /**
           * Verifies that the actual [ShellScreen] contains all the given
           * values, ignoring whitespace differences.
           *
           * This is particularly useful with long messages since the screen is
           * an emulated terminal, breaking lines when they exceed the terminal
           * width.
           */
          fun ShellScreenAssert.containsTextIgnoringWhitespaces(
              vararg values: String
          ): ShellScreenAssert {
              assertThat(this.actual().lines().joinToString("\n"))
                  .containsIgnoringWhitespaces(*values)
              return this
          }
  
      }
  
      /**
       * Custom [CommandExceptionResolver] to assist with testing.
       *
       * Without this resolver, exceptions would be hidden, discarded by
       * [ShellTestClient].
       */
      class ExceptionResolver : CommandExceptionResolver {
  
          var exception: Exception? = null
  
          override fun resolve(exception: Exception): CommandHandlingResult {
              this.exception = exception
              return CommandHandlingResult.of(
                  "Exception occurred: " + getRootCauseMessage(exception),
                  1
              )
          }
  
          /**
           * Rethrow exception if had been caught by this resolver.
           */
          fun check() = exception?.let { throw it }
  
      }
  
      @TestConfiguration
      class Config {
  
          @Bean
          fun exceptionResolver() = ExceptionResolver()
  
      }
  
  }

Quite a bit of a set back. It seems like Spring Shell is in flux. Should I hold off on the 4.0.0 upgrade, wait and see if any of the above issues are resolved first?

[ThomasVitale]

I've been having some of the same issues. I registered some of them:

• Add breaking change to 4.0 migration guide: GraalVM not supported for annotated commands #1260
• Add breaking change to 4.0 migration guide: Option arity feature has been removed #1263
• Add breaking change to 4.0 migration guide: Non-interactive mode is not the default anymore #1264
• Commands fail in 4.0 if no short name or long name are specified #1261
• Boolean command options fail in 4.0 without explicit value #1262
• Exception handling APIs removed in 4.0 without replacement #1265
• Restore support for command grouping at class level in 4.0 #1266
• Built-in commands not available for non-interactive mode in 4.0 #1268
• Configuration properties metadata are missing in 4.0 #1267

I would suggest raising dedicated GitHub issues for each problem to make it easier to handle them.

[fmbenhassine]

Thank you for the detailed feedback, @gturner834 ! And thank you @ThomasVitale for the follow up on this. I will reply in separate comments so we can elaborate on each topic with discussion threads.

Everything you can do with Spring Shell v3 is possible with v4. Most issues reported here seem to be related to undocumented changes in the migration guide (apologies for the confusion, I will update the guide asap). I will also explain the reasoning behind each change and how to handle things in v4. I understand that major releases can cause some migration effort/issues, but I believe v4 includes many necessary changes that are required for the long term sustainability and maintenance of the project. As with every overhaul, I am expecting some bumps and corner cases that were missed in the GA, but I am committed to release 4.0.1 (planned for January 21st) and 4.0.2 to fix major issues if any as soon as possible and to help our users migrate their apps to v4.

Please note that v4.0 is a foundational release, which I believe provides a strong base compared to previous versions to maintain Spring Shell in the future, and I am open to adapt v4 and try to align it with v3 when it makes sense.

[ThomasVitale]

Thanks so much for looking into these issues! If there's anything I can do to help, I'm available to contribute.

[fmbenhassine]

Thank YOU for all your feedback on v4! You already helped by reporting all these issues, I really appreciate that 🙏

If you want to contribute, you can check issues that are validated and planned for 4.0.1. Many thanks upfront.

[fmbenhassine]

1. Interactive and non-interactive modes are now mutually exclusive.

Following the unix philosophy of doing one thing at a time and doing it well, it does not make sense for a shell application to be interactive and non-interactive at the same time. The fact that it was possible to be in both modes at the same time in v3 resulted in several problems:

• Confusing configuration and precedence between shell runners (there is even a "Caution" about this in the getting started guide)
• The use of an InteractionMode enumeration to mark commands as being interactive or not and all the complexity of code and usage around it. This is a direct consequence of trying to make one thing (the shell runner) do two things at the same time. The outcome of a command should really be the same regardless of the execution mode and all commands should be designed irrespective of the interaction mode.
• As a direct consequence of the previous point, it was confusing to test a command as one had to know in which mode it was designed to be in and choose the test session mode accordingly (see Testing Interactive Shell Commands Doesn't Work #536, and all linked issue in Redesign test utilities #1234 in which we redesigned test utilities as well).
• The implementation of non-interactive shells was incorrect as it was based on the same base class, leading to non natural flags in the code and methods names like handlingResultNonInt and processExceptionNonInt, see Incorrect implementation of non-interactive shells #1218. As a reminder, even if this is a non user-facing issue, I always try to think about the code structure and maintainability for the long term support of the project.

In v4, you have to choose which mode to be in from the beginning and all these problems just disappear by design/construction. I updated the migration guide with a section about this change: Shell interactivity changes

[fmbenhassine]

2. @CommandScan was removed and the replacement CommandRegistryAutoConfiguration which only scans from the
   @SpringBootApplication declaring package.

One of the main themes of v4 is API/Annotation simplification and we really don't need a separate annotation for command scanning as we already have @ComponentScan that should be enough in a non-boot world. In a Boot setup, we have @SpringBootApplication(scanBasePackages = "com.acme.commands") that should work as well. Did you try that? the current command discovery mechanism is based on bean introspection from the application context, so I am expecting things to work OOTB with the standard @ComponentScan or @SpringBootApplication(scanBasePackages = "com.acme.commands"). If that is not the case, then please open an issue and I will fix that.

[fmbenhassine]

3. @OptionValues was removed, replaced with @Command-level declaration, causing a lot of boilerplate.
   TODO("Need to build one of these for every command, with hard-coded parameter names")

With v3, You would also need to build one these for every option, so the "boilerplate" is equally the same, it's just now centralized (which is better than scattered). However, I am not sure why it is an issue to build a completer for every command, that's part of the command customisation (each command has its own completer, availability provider, etc).

The one big issue though of having a completer per option (apart from having to define many beans for a single command), is that providing cross options completion is just impossible. Here is an example:

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();
	};
}

As you can see, providing completion for names based on the gender is possible with this approach compared to v3. I updated the migration guide with a section about this: Command completion

In addition, using @OptionValues with no provider on enums was working great before, and will now have to construct EnumCompletionProvider for each command.

To be honest, I was not aware of that in v3. But we can improve this in the default completer of v4: if the current option is an enum, the completer should return the enum's values. I created #1282 to align things with v3.

[fmbenhassine]

4. @command is no longer applicable to classes (methods only), hierarchy/sub-commands no longer supported.

This is mentioned in the migration guide here.

hierarchy/sub-commands no longer supported.

This is not accurate, sub-commands are still supported, and the Spring PetClinic CLI app is a working sample with sub-commands.

Now, regarding the duplication in the command prefix (in the example you shared, you are concatenating command names but the name attribute actually accepts an array of Strings) and group, you can indeed use constants for that, and that's the way to go in v4.0.0. You provided an example, but I had another one that I will add here for reference:

import org.springframework.shell.core.command.annotation.Command;
import org.springframework.stereotype.Component;

@Component
public class GitHubCommands {

	private static final String GROUP = "Github commands";
	private static final String ROOT_COMMAND = "github";

	private boolean connected = false;

	@Command(name = {ROOT_COMMAND, "login"}, description = "Login to GitHub", group = GROUP)
	public void login() {
		// handle authentication logic here
		connected = true;
	}


	@Command(name = {ROOT_COMMAND, "logout"}, description = "Logout from GitHub", group = GROUP)
	public void logout() {
		// handle logout logic here
		connected = false;
	}

}

I really don't see the need for using the same annotation at two different levels to inherit common attributes, especially an @Command annotation (named in singular) at a class level in which multiple commands are defined (how confusing is that?).

Spring Shell v2 has a ShellCommandGroup which was way less confusing than using the same @Command annotation at two different levels as in v3. This point was already reported in #1266, which suggests a similar way as v2 with the CommandGroup, and I am open to improve things with a different annotation if really needed. But for now, there is no plan to revert @Command back as a class-level annotation. Using constants is the way to go as of 4.0.x until we improve things later. BTW, this is only an "issue" for the annotation approach, as you could use the programmatic approach and make all related annotations inherit from a base class (AbstractCommand for instance) and define common attributes at the base class level.

Last thing, it'a amazing how no one is complaining about not being able to inherit common attributes for related Spring @Beans defined in the same @Configuration class, because this is to me (technically) the exact same problem:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
//@Configuration(autowireCandidate = false) // Why isn't this a problem even if not possible? 
public class RelatedBeans {

	public static final boolean AUTOWIRE_CANDIDATE = false;

	@Bean(autowireCandidate = AUTOWIRE_CANDIDATE)
	public String bean1() {
		return "bean1";
	}

	@Bean(autowireCandidate = AUTOWIRE_CANDIDATE)
	public String bean2() {
		return "bean2";
	}

}

[ThomasVitale]

Thanks for the explanation! To me the use case of having a class-level annotation and a method-level annotation is very similar to how @RequestMapping and similar annotations work in Spring WebMVC regarding the path.

In Spring WebMVC I can do this and the path defined in the class-level annotation is combined with the path defined on the method-level annotation. Very convenient, clear, and readable. At a glance, I can tell all the mappings defined in this class have a /demo base path.

@RestController
@RequestMapping(path = "/demo")
class DemoController {

	@GetMapping(path = "/hello")
	String hello() {
		return "Hello World!";
	}

	@GetMapping(path = "/greetings")
	String greetings() {
		return "Greetings, World!";
	}
	
}

I would be very inconvenient having to do something like the following, without the class-level annotation. This is more error-prone and not much readable. I cannot safely infer that all the mappings defined in this class have a /demo base path unless I inspect the code for all of them, and possibly write auto-tests to ensure I don't miss one or misspell anything.

@RestController
class DemoController {
	
	private static final String BASE_PATH = "/demo";

	@GetMapping(path = BASE_PATH + "/hello")
	String hello() {
		return "Hello World!";
	}

	@GetMapping(path = BASE_PATH + "/greetings")
	String greetings() {
		return "Greetings, World!";
	}

}

The same model applies to other Spring projects, such as for GraphQL or for WebSockets, where the mappings paths are combined in a similar way.

I still believe it would be nice to introduce a new, dedicated class-level annotation (I agree that re-using @Command was confusing), as I described in #1266.

[fmbenhassine]

Thank you for the feedback, @ThomasVitale . Note how the base path and the actual path are defined with different annotations (@RequestMapping(path = "/demo") and @GetMapping(path = "/hello")) and not the same @GetMapping annotation, which is exactly the point I was trying to make when I said: "I really don't see the need for using the same annotation at two different levels to inherit common attributes, especially an @command annotation (named in singular) at a class level in which multiple commands are defined (how confusing is that?)."

I still believe it would be nice to introduce a new, dedicated class-level annotation (I agree that re-using @Command was confusing), as I described in #1266.

Agreed. As mentioned previously, I am open to improve things with a different annotation as in v2 if needed. But let's discuss that in #1266

[fmbenhassine]

5. Optional parameters spam warning messages.

This was reported in #1245 and is planned for 4.0.1

[fmbenhassine]

6. @Option no longer supports alternative/alias longNames (array vs. single value).

This is really one of the "superfluous" features of Spring Shell 3 (with its OptionNameModifier sister..).

Please take a look at #1220 where I explain the rationale behind this simplification with some examples of modern and well-established tools that have a single value for short/long option names.

However, I noticed that this was missing from the migration guide, so I added a note about it here: Command options.

[fmbenhassine]

7 Exception handling in interactive mode does not report cause

This is indeed a regression. I created to #1285 to track it and planned it for the upcoming 4.0.1

stacktrace command no longer exists.

This was reported in #1280. The change was documented (see the Debug Mode section), but not mentioned in the migration guide, my bad.. I just added a section about it here.

The main reason of this change is that the stacktrace command requires global mutable state to keep the stacktrace of the last command and there is no good place for this global state.

Similar to many popular CLI frameworks/tools, Spring Shell 4 introduce a debug mode, which when enabled, prints the stack trace of the last command right away instead of the user asking for it right after. So the idea is that you configure the shell in debug mode once (like for example running Maven with -X flag) and have the stack trace of every error, instead of having to type stacktrace every time an error occurs.

[fmbenhassine]

8. Regression with help

Reported in #1271 and planned for 4.0.1

[fmbenhassine]

9. @Option has removed label property pertaining to help (e.g. see DATE, NAME, EMAIL, etc. in 3.4 example above).

Another superfluous / confusing feature. A label/tag would be useful in ordering, grouping, querying things (a good example of label usage is in k8s pod labelling, where one could query for pods having a specific label) but none of this is used here. It's only used for the help string. In the same spirit of simplifying things, an option should have a single short/long name. The migration guide was updated accordingly.

[fmbenhassine]

10. Regression with version

Similar to help, I think this was a regression of the removal of the template engine (ST4) from the core module. I will put this back in 4.0.1: #1286

[fmbenhassine]

11. The @ShellTest overhaul looks like it'll be helpful, but I'm still working through the above issues, unable to execute tests just yet...

That was really one of the areas of the framework where I was astonished many times both in terms of feature design/usability and by the code behind the testing APIs.. There is no point in repeating what I have said in #1234 (please see related issues as well), but you basically have two options:

• Use the new Spring Shell 4 test utilities to mimic user's input and assert on the shell's output
• Not use Spring Shell test utilities (ie complete black-box end-to-end testing of a Spring Shell app) and use your preferred test libraries to assert on the output. Here is an example with Spring Boot utilities which I recently added mentioned here

Please let me know if you need support in migrating your tests and I will be happy to help.

[fmbenhassine]

Quite a bit of a set back. It seems like Spring Shell is in flux.

Coming from Spring Shell 3, I can understand that because Spring Shell 4 is quite different from v3. But for someone new to Spring Shell, things in v4 are:

• more natural to work with than v3 (even in terms of APIs naming like Command instead of CommandRegistration, CommandRegistry instead of CommandCatalog, etc)
• the getting started experience is much better (real world command names like in the PetClinic sample and others compared to anno1 arg1 arg2, e2e annox option-value..) and less frustrating Unexpected behavior with @Command annotation #1158 (users are two commands away from having something up and running)
• the API is modernised (usage of Java records) and safer in terms of nullability thanks to jSpecify annotations
• the modularity of the framework is more streamlined and aligned with the Spring Boot naming standards
• the testing APIs are less confusing
• And that was not all! We were not able to include some other improvements like the removal of hibernate validator from the core module, the reactor dependency, the dependency to spring messaging as well, complete the experimental Terminal UI framework, etc

So all in all, and while I was expecting some bumps and corner cases in this 4.0 GA, I strongly believe that Spring Shell 4 (once stabilized in 4.0.1, 4.0.2) will be foundational release that provides a strong base for the long term sustainability of the project.

Should I hold off on the 4.0.0 upgrade, wait and see if any of the above issues are resolved first?

As mentioned previously, most of these issues where unfortunately undocumented in the migration guide (apologies for the confusion, but now I updated the guide accordingly) and valid ones will be fixed in 4.0.1 planned for January 21st, so it is up to you to migrate now of wait for 4.0.1. After all, nothing is really blocking as far as I can tell: all issues are either valid minor bugs, or improvements to make things work as in v3 where it makes sense.

I hope I answered all your questions/ concerns, but please let me know in comments/threads if you need help on migrating to v4.