Spring Boot CLI

The Spring Boot CLI is a command-line tool for quickly bootstrapping and experimenting with Spring Boot. Its two headline uses are scaffolding new projects with spring init (a command-line front end to the Spring Initializr) and running self-contained Groovy scripts without writing a build file at all. It is optional, you never need it to build a normal project, but it is handy for prototyping and scripting.

Installing the CLI

The recommended installer is SDKMAN!, which manages JVM tools and lets you switch versions easily.

# Install SDKMAN (if you don't have it)
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Install the Spring Boot CLI
sdk install springboot

# Verify
spring --version

Output:

Spring CLI v3.5.0

On macOS you can use Homebrew instead:

brew tap spring-io/tap
brew install spring-boot

Tip: SDKMAN is the most portable option across Linux and macOS, and sdk install springboot 3.5.0 lets you pin a specific version that matches your projects. Manual installs (download, unzip, add bin to PATH) work too but are harder to keep current.

Scaffolding projects with `spring init`

spring init calls the same service as start.spring.io, so anything you can pick in the web UI you can pass as a flag. This is the fastest way to create a project from a terminal.

spring init \
  --boot-version=3.5.0 \
  --java-version=21 \
  --type=maven-project \
  --packaging=jar \
  --group-id=com.devcraftly \
  --artifact-id=demo \
  --dependencies=web,data-jpa,h2,lombok \
  demo

Output:

Using service at https://start.spring.io
Project extracted to '/home/dev/demo'

A few useful variations:

# List every supported option (dependencies, boot versions, types)
spring init --list

# Generate a Gradle project instead of Maven
spring init --type=gradle-project --dependencies=web my-app

# Download the raw zip instead of extracting
spring init --dependencies=web -x demo.zip

Note: spring init requires network access because it delegates to the Initializr web service. Behind a proxy or offline, generate from the web UI or a cached template instead.

Running Groovy scripts

The CLI’s most distinctive feature is running a Spring Boot application from a single Groovy file. The CLI auto-imports common Spring types and infers dependencies (“grabbing” them) from the annotations you use, so there is no pom.xml and no explicit imports for the basics.

// app.groovy
@RestController
class HelloController {

    @GetMapping("/")
    String home() {
        "Hello from the Spring Boot CLI!"
    }
}

Run it directly:

spring run app.groovy

Output:

 :: Spring Boot ::                (v3.5.0)
INFO  Tomcat started on port 8080 (http) with context path '/'
INFO  Started application in 2.1 seconds (process running for 2.6)

Then call it like any other endpoint:

curl http://localhost:8080/

Output:

Hello from the Spring Boot CLI!

The CLI recognizes annotations such as @RestController and @EnableAutoConfiguration, resolves the matching starters, and compiles and runs the script, a genuinely zero-config demo.

CLI commands at a glance

Command	Purpose
`spring init`	Generate a project via the Initializr
`spring init --list`	Show available options and dependencies
`spring run script.groovy`	Compile and run a Groovy script as an app
`spring --version`	Print the installed CLI version
`spring help`	Show all commands and flags

When (and when not) to use the CLI

Reach for the CLI when you want to scaffold a project from the terminal or prototype an idea in a few lines of Groovy, for example to reproduce a bug, demo a concept, or sketch an endpoint. It shines for throwaway experiments.

Warning: Groovy scripts run through spring run are for prototyping, not production. Real applications belong in a proper Maven or Gradle project with version control, tests, and a build pipeline. Use spring init to generate that project and move on.

For everyday work, prefer a generated project plus the build wrapper, see Maven vs Gradle and running & packaging.

Spring Boot CLI

Installing the CLI

Scaffolding projects with spring init

Running Groovy scripts

CLI commands at a glance

When (and when not) to use the CLI

Related Topics

Scaffolding projects with `spring init`