Spring Boot CLI: Rapid Prototyping with Groovy and the Command Line

I've been building Spring applications since the XML-hell days of Spring 2.5, and I've seen every trend come and go. When Spring Boot CLI hit 1.0 in 2014, I dismissed it as a toy. "Real developers use proper build tools," I thought. Then I spent a weekend rewriting a 500-line prototype that took two days to setup in Maven, into a 30-line Groovy script that ran in 3 seconds. I was wrong. Dead wrong. Spring Boot CLI is not a replacement for Maven or Gradle in production—it's a scalpel for rapid prototyping, demos, integration tests, and internal tools where speed matters more than maintainability. The CLI leverages Groovy's syntactic sugar (think Python meets Java) and Spring Boot's auto-configuration to eliminate boilerplate. You write a single .groovy file, declare dependencies with @Grab, and run spring run app.groovy. Under the hood, it resolves dependencies via Ivy, starts an embedded Tomcat (or Netty for reactive), and applies auto-configuration. I've used it to build a real-time analytics dashboard for a client demo in 45 minutes—something that would have taken 4 hours with the full Maven setup. But here's the catch: the CLI has hidden traps. Default logging levels can flood your console. Classpath scanning can pull in unintended beans. And if you're not careful, your "quick prototype" becomes a production albatross that nobody wants to refactor. This guide covers what the docs skip—the production scars, the debugging tricks, and the edge cases that will bite you at 2 AM.

Getting Started: Your First Groovy REST API in 30 Seconds

Let's cut the fluff. Install Spring Boot CLI via SDKMAN: sdk install springboot 3.2.0. Or if you're on macOS, brew install springboot. Now create a file called hello.groovy with the following code. The magic is in @Grab('spring-boot-starter-web')—it tells the CLI to resolve the entire Spring Web stack (Tomcat, Jackson, validation) as a transitive dependency. No pom.xml, no build.gradle, no waiting for Maven to download the internet. Just run spring run hello.groovy and you'll see Tomcat started on port 8080 in under 5 seconds. The @RestController and @RequestMapping are standard Spring annotations, but Groovy lets you omit semicolons, public modifiers, and parentheses for method calls. This is the killer feature for demos: you can write a working REST API in front of a client during a meeting, and they'll think you're a wizard. But here's the production insight—this simplicity is a double-edged sword. The CLI uses Groovy's @CompileStatic by default, which means you lose some dynamic features. If you need runtime metaprogramming, you'll need to add @CompileDynamic explicitly.

@Grab('spring-boot-starter-web:3.2.0')
@RestController
class HelloController {
    @RequestMapping('/')
    String home() {
        "Hello, Spring Boot CLI!"
    }
}

What the Official Docs Won't Tell You

After years of using Spring Boot CLI in real projects, I've compiled a list of undocumented behaviors that will save you hours of debugging. First, the CLI's classpath resolution is not the same as Maven's. The CLI uses Apache Ivy under the hood, which resolves dependencies differently—it doesn't honor Maven's dependency mediation rules perfectly. This means you can end up with duplicate jars or conflicting versions. I once spent 3 hours debugging a ClassNotFoundException for HikariCP because the CLI pulled an older version from a transitive dependency. Second, the default logging configuration uses Logback with DEBUG level for Spring Framework classes. On a real project with 50+ endpoints, this will flood your console with 10,000+ lines per minute. Add @Grab('spring-boot-starter-logging') and create a logback.xml in the same directory to override this. Third, the CLI's auto-configuration scans the entire classpath, which means any library on the classpath can trigger auto-configuration. For example, adding @Grab('h2') will automatically configure an H2 in-memory database and a DataSource bean—even if you only wanted the H2 console for testing. To disable specific auto-configuration classes, use @EnableAutoConfiguration(exclude = ...) in your Groovy script. Finally, the CLI does not support multi-module projects out of the box. If you need to share code between scripts, you'll have to use @Grab with a local jar or publish your common classes as a separate artifact.

@Grab('spring-boot-starter-web:3.2.0')
@Grab('spring-boot-starter-logging')
@GrabExclude('org.springframework.boot:spring-boot-starter-logging')
@RestController
class LoggingDemo {
    @RequestMapping('/')
    String home() {
        log.info("Handling request")
        "OK"
    }
}

Building a Real-Time Analytics Dashboard with WebSocket

Let's build something more substantial: a real-time analytics dashboard that streams data via WebSocket. This demonstrates how CLI can handle non-trivial use cases. The @Grab('spring-boot-starter-websocket') pulls in the WebSocket support, including STOMP messaging. We'll create a scheduler that publishes random analytics events every second. In production, this would come from a Kafka topic or a database change stream. The @EnableScheduling annotation triggers the scheduler, and SimpMessagingTemplate broadcasts to all subscribers on the /topic/analytics destination. The Groovy syntax makes this incredibly concise—15 lines for what would be 50+ in Java with all the imports. But here's the production reality: WebSocket sessions in the CLI default to in-memory storage. If your CLI app restarts (which happens often during prototyping), all sessions are lost. For a real demo, this is fine. But if someone suggests using this for a production load test, push back hard. You'll need a proper WebSocket broker (like RabbitMQ or Redis) for session persistence.

@Grab('spring-boot-starter-websocket:3.2.0')
@Grab('spring-boot-starter-web')
@EnableScheduling
@SpringBootApplication
class AnalyticsDashboard {
    @Autowired SimpMessagingTemplate messagingTemplate
    
    @Scheduled(fixedRate = 1000)
    void publishEvent() {
        def event = [timestamp: System.currentTimeMillis(),
                     metric: Math.random() * 100]
        messagingTemplate.convertAndSend("/topic/analytics", event)
    }
}

Database Integration: JPA with H2 in 10 Lines

One of the most common prototyping needs is database access. The CLI makes this trivial with @Grab('spring-boot-starter-data-jpa') and @Grab('h2'). In the following example, we define a JPA entity User and a repository interface UserRepository. Spring Data JPA automatically implements CRUD operations at runtime. The @PostConstruct method seeds some data on startup. This is a perfect pattern for a quick admin panel or a proof-of-concept for a new feature. But here's the trap: the CLI uses an embedded H2 database by default. If you restart the app, all data is gone. For prototyping, this is fine. But I've seen teams accidentally deploy CLI prototypes to staging environments with H2, then wonder why data disappears after a deployment. Always use a proper database profile for anything beyond local testing. Also, the CLI's auto-configuration will create tables based on your entities, but it won't handle migrations. If you change an entity, you'll need to delete the database file or use spring.jpa.hibernate.ddl-auto=update (which is dangerous in production).

@Grab('spring-boot-starter-data-jpa:3.2.0')
@Grab('h2:2.2.224')
@SpringBootApplication
class DatabaseDemo {
    @Autowired UserRepository repo
    
    @PostConstruct
    void init() {
        repo.save(new User(name: "Alice", email: "alice@example.com"))
        println "Users: ${repo.findAll()}"
    }
}

@Entity
class User {
    @Id @GeneratedValue Long id
    String name, email
}

CLI with Actuator and Metrics for Production Monitoring

You can add Spring Boot Actuator to your CLI app for production-grade monitoring. The @Grab('spring-boot-starter-actuator') enables endpoints like /actuator/health, /actuator/metrics, and /actuator/info. In the example, we expose all endpoints via HTTP. This is incredibly useful for demos where you need to show health checks, request metrics, or even thread dumps. I once used a CLI app with Actuator to debug a memory leak in a client's staging environment—the /actuator/threaddump endpoint revealed a stuck thread immediately. However, the CLI's default security configuration is wide open. By default, Actuator endpoints are accessible without authentication. For a local demo, this is fine. But if you deploy this to a shared network, you're exposing sensitive information like environment variables and heap dumps. Always add @Grab('spring-boot-starter-security') and configure basic auth or use the management.endpoints.web.exposure.include=health,info to limit exposure.

@Grab('spring-boot-starter-web:3.2.0')
@Grab('spring-boot-starter-actuator')
@SpringBootApplication
class ActuatorDemo {
    @RequestMapping('/')
    String home() { "OK" }
}
// Run with: spring run actuator.groovy --management.endpoints.web.exposure.include=*

Testing CLI Applications with JUnit and Mockito

Yes, you can write tests for CLI apps. The @Grab('spring-boot-starter-test') pulls in JUnit 5, Mockito, and Spring Test. The trick is to use @SpringBootTest with a Groovy test class. In the example, we test the HelloController using TestRestTemplate. This is invaluable for integration testing during prototyping. However, the CLI's test support has limitations. First, the test class must be in the same directory as the main script—the CLI doesn't support a separate test source set. Second, the @SpringBootTest annotation will start the full application context, which can be slow for unit tests. For fast unit tests, use @WebMvcTest to only load the web layer. Third, the CLI uses Groovy's @CompileStatic by default, which can interfere with Mockito's bytecode manipulation. If you get a MockitoException, add @CompileDynamic to your test class. I learned this the hard way when a team spent 4 hours debugging a test that passed in IntelliJ but failed on the CLI.

@Grab('spring-boot-starter-test:3.2.0')
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class HelloControllerTest {
    @Autowired TestRestTemplate restTemplate
    
    @Test
    void testHome() {
        def response = restTemplate.getForEntity('/', String.class)
        assert response.statusCode == HttpStatus.OK
        assert response.body == 'Hello, Spring Boot CLI!'
    }
}

CLI for Microservices: Service Discovery with Eureka

The CLI can even participate in a microservices ecosystem. Add @Grab('spring-cloud-starter-netflix-eureka-client') to register your CLI app with a Eureka server. In the example, we configure the application name and Eureka server URL using -- arguments. This is surprisingly useful for demos where you want to show service discovery, load balancing, and resilience patterns. I've built a 3-service demo (order, payment, notification) entirely with CLI scripts for a conference talk. Each script was under 30 lines. The audience was amazed. But here's the production reality: CLI apps are not designed for long-running microservices. They lack proper graceful shutdown, health check hooks, and lifecycle management. If a CLI app crashes, there's no automatic restart (unless you wrap it in a systemd service or Docker). Also, the CLI's classpath is static—you can't add new dependencies at runtime. For a real microservice, use a proper Spring Boot jar with Maven/Gradle.

@Grab('spring-cloud-starter-netflix-eureka-client:4.1.0')
@Grab('spring-boot-starter-web')
@SpringBootApplication
@EnableDiscoveryClient
class EurekaDemo {
    @RequestMapping('/')
    String home() { "Registered with Eureka" }
}
// Run with: spring run eureka-client.groovy --spring.application.name=cli-demo --eureka.client.serviceUrl.defaultZone=http://localhost:8761/eureka

Advanced: Custom Auto-Configuration and CLI Extensions

The CLI supports custom auto-configuration via @Grab and @Configuration. You can create reusable Groovy scripts that act as libraries. For example, create a my-lib.groovy that defines a custom @Configuration class, then use @Grab('my-lib.groovy') in other scripts. This is how you build a CLI-based microframework for your team. I've seen teams create shared libraries for logging, metrics, and security that can be pulled into any CLI prototype with a single @Grab. However, there's a catch: the CLI's classloader is not isolated between scripts. If two scripts define the same bean, you'll get a BeanDefinitionStoreException. To avoid this, use @ConditionalOnMissingBean in your configuration. Also, the CLI does not support versioning for local scripts—you'll need to manage that manually. For a real shared library, publish it as a proper jar to a Maven repository and use @Grab('com.example:my-lib:1.0.0').

@Grab('spring-boot-starter-web:3.2.0')
@Configuration
class CustomConfig {
    @Bean
    @ConditionalOnMissingBean
    MyService myService() {
        new MyService()
    }
}

class MyService {
    String greet() { "Hello from custom config!" }
}