[[cli]] = Spring Boot CLI include::attributes.adoc[] The Spring Boot CLI is a command line tool that you can use if you want to quickly develop a Spring application. It lets you run Groovy scripts, which means that you have a familiar Java-like syntax without so much boilerplate code. You can also bootstrap a new project or write your own command for it. [[cli-installation]] == Installing the CLI The Spring Boot CLI (Command-Line Interface) can be installed manually by using SDKMAN! (the SDK Manager) or by using Homebrew or MacPorts if you are an OSX user. See _<>_ in the "`Getting started`" section for comprehensive installation instructions. [[cli-using-the-cli]] == Using the CLI Once you have installed the CLI, you can run it by typing `spring` and pressing Enter at the command line. If you run `spring` without any arguments, a simple help screen is displayed, as follows: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring usage: spring [--help] [--version] [] Available commands are: run [options] [--] [args] Run a spring groovy script _... more command help is shown here_ ---- You can type `spring help` to get more details about any of the supported commands, as shown in the following example: [indent=0] ---- $ spring help run spring run - Run a spring groovy script usage: spring run [options] [--] [args] Option Description ------ ----------- --autoconfigure [Boolean] Add autoconfigure compiler transformations (default: true) --classpath, -cp Additional classpath entries --no-guess-dependencies Do not attempt to guess dependencies --no-guess-imports Do not attempt to guess imports -q, --quiet Quiet logging -v, --verbose Verbose logging of dependency resolution --watch Watch the specified file for changes ---- The `version` command provides a quick way to check which version of Spring Boot you are using, as follows: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring version Spring CLI v{spring-boot-version} ---- [[cli-run]] === Running Applications with the CLI You can compile and run Groovy source code by using the `run` command. The Spring Boot CLI is completely self-contained, so you do not need any external Groovy installation. The following example shows a "`hello world`" web application written in Groovy: .hello.groovy [source,groovy,indent=0,subs="verbatim,quotes,attributes"] ---- @RestController class WebApplication { @RequestMapping("/") String home() { "Hello World!" } } ---- To compile and run the application, type the following command: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring run hello.groovy ---- To pass command-line arguments to the application, use `--` to separate the commands from the "`spring`" command arguments, as shown in the following example: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring run hello.groovy -- --server.port=9000 ---- To set JVM command line arguments, you can use the `JAVA_OPTS` environment variable, as shown in the following example: [indent=0,subs="verbatim,quotes,attributes"] ---- $ JAVA_OPTS=-Xmx1024m spring run hello.groovy ---- NOTE: When setting `JAVA_OPTS` on Microsoft Windows, make sure to quote the entire instruction, such as `set "JAVA_OPTS=-Xms256m -Xmx2048m"`. Doing so ensures the values are properly passed to the process. [[cli-deduced-grab-annotations]] ==== Deduced "`grab`" Dependencies Standard Groovy includes a `@Grab` annotation, which lets you declare dependencies on third-party libraries. This useful technique lets Groovy download jars in the same way as Maven or Gradle would but without requiring you to use a build tool. Spring Boot extends this technique further and tries to deduce which libraries to "`grab`" based on your code. For example, since the `WebApplication` code shown previously uses `@RestController` annotations, Spring Boot grabs "Tomcat" and "Spring MVC". The following items are used as "`grab hints`": |=== | Items | Grabs | `JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource` | JDBC Application. | `@EnableJms` | JMS Application. | `@EnableCaching` | Caching abstraction. | `@Test` | JUnit. | `@EnableRabbit` | RabbitMQ. | extends `Specification` | Spock test. | `@EnableBatchProcessing` | Spring Batch. | `@MessageEndpoint` `@EnableIntegration` | Spring Integration. | `@Controller` `@RestController` `@EnableWebMvc` | Spring MVC + Embedded Tomcat. | `@EnableWebSecurity` | Spring Security. | `@EnableTransactionManagement` | Spring Transaction Management. |=== TIP: See subclasses of {spring-boot-cli-module-code}/compiler/CompilerAutoConfiguration.java[`CompilerAutoConfiguration`] in the Spring Boot CLI source code to understand exactly how customizations are applied. [[cli-default-grab-deduced-coordinates]] ==== Deduced "`grab`" Coordinates Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency without a group or version (for example, `@Grab('freemarker')`). Doing so consults Spring Boot's default dependency metadata to deduce the artifact's group and version. NOTE: The default metadata is tied to the version of the CLI that you use. It changes only when you move to a new version of the CLI, putting you in control of when the versions of your dependencies may change. A table showing the dependencies and their versions that are included in the default metadata can be found in the <>. [[cli-default-import-statements]] ==== Default Import Statements To help reduce the size of your Groovy code, several `import` statements are automatically included. Notice how the preceding example refers to `@Component`, `@RestController`, and `@RequestMapping` without needing to use fully-qualified names or `import` statements. TIP: Many Spring annotations work without using `import` statements. Try running your application to see what fails before adding imports. [[cli-automatic-main-method]] ==== Automatic Main Method Unlike the equivalent Java application, you do not need to include a `public static void main(String[] args)` method with your `Groovy` scripts. A `SpringApplication` is automatically created, with your compiled code acting as the `source`. [[cli-default-grab-deduced-coordinates-custom-dependency-management]] ==== Custom Dependency Management By default, the CLI uses the dependency management declared in `spring-boot-dependencies` when resolving `@Grab` dependencies. Additional dependency management, which overrides the default dependency management, can be configured by using the `@DependencyManagementBom` annotation. The annotation's value should specify the coordinates (`groupId:artifactId:version`) of one or more Maven BOMs. For example, consider the following declaration: [source,groovy,indent=0] ---- @DependencyManagementBom("com.example.custom-bom:1.0.0") ---- The preceding declaration picks up `custom-bom-1.0.0.pom` in a Maven repository under `com/example/custom-versions/1.0.0/`. When you specify multiple BOMs, they are applied in the order in which you declare them, as shown in the following example: [source,java,indent=0] ---- @DependencyManagementBom(["com.example.custom-bom:1.0.0", "com.example.another-bom:1.0.0"]) ---- The preceding example indicates that the dependency management in `another-bom` overrides the dependency management in `custom-bom`. You can use `@DependencyManagementBom` anywhere that you can use `@Grab`. However, to ensure consistent ordering of the dependency management, you can use `@DependencyManagementBom` at most once in your application. [[cli-multiple-source-files]] === Applications with Multiple Source Files You can use "`shell globbing`" with all commands that accept file input. Doing so lets you use multiple files from a single directory, as shown in the following example: [indent=0] ---- $ spring run *.groovy ---- [[cli-jar]] === Packaging Your Application You can use the `jar` command to package your application into a self-contained executable jar file, as shown in the following example: [indent=0] ---- $ spring jar my-app.jar *.groovy ---- The resulting jar contains the classes produced by compiling the application and all of the application's dependencies so that it can then be run by using `java -jar`. The jar file also contains entries from the application's classpath. You can add and remove explicit paths to the jar by using `--include` and `--exclude`. Both are comma-separated, and both accept prefixes, in the form of "`+`" and "`-`", to signify that they should be removed from the defaults. The default includes are as follows: [indent=0] ---- public/**, resources/**, static/**, templates/**, META-INF/**, * ---- The default excludes are as follows: [indent=0] ---- .*, repository/**, build/**, target/**, **/*.jar, **/*.groovy ---- Type `spring help jar` on the command line for more information. [[cli-init]] === Initialize a New Project The `init` command lets you create a new project by using https://start.spring.io without leaving the shell, as shown in the following example: [indent=0] ---- $ spring init --dependencies=web,data-jpa my-project Using service at https://start.spring.io Project extracted to '/Users/developer/example/my-project' ---- The preceding example creates a `my-project` directory with a Maven-based project that uses `spring-boot-starter-web` and `spring-boot-starter-data-jpa`. You can list the capabilities of the service by using the `--list` flag, as shown in the following example: [indent=0] ---- $ spring init --list ======================================= Capabilities of https://start.spring.io ======================================= Available dependencies: ----------------------- actuator - Actuator: Production ready features to help you monitor and manage your application ... web - Web: Support for full-stack web development, including Tomcat and spring-webmvc websocket - Websocket: Support for WebSocket development ws - WS: Support for Spring Web Services Available project types: ------------------------ gradle-build - Gradle Config [format:build, build:gradle] gradle-project - Gradle Project [format:project, build:gradle] maven-build - Maven POM [format:build, build:maven] maven-project - Maven Project [format:project, build:maven] (default) ... ---- The `init` command supports many options. See the `help` output for more details. For instance, the following command creates a Gradle project that uses Java 8 and `war` packaging: [indent=0] ---- $ spring init --build=gradle --java-version=1.8 --dependencies=websocket --packaging=war sample-app.zip Using service at https://start.spring.io Content saved to 'sample-app.zip' ---- [[cli-shell]] === Using the Embedded Shell Spring Boot includes command-line completion scripts for the BASH and zsh shells. If you do not use either of these shells (perhaps you are a Windows user), you can use the `shell` command to launch an integrated shell, as shown in the following example: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring shell *Spring Boot* (v{spring-boot-version}) Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit. ---- From inside the embedded shell, you can run other commands directly: [indent=0,subs="verbatim,quotes,attributes"] ---- $ version Spring CLI v{spring-boot-version} ---- The embedded shell supports ANSI color output as well as `tab` completion. If you need to run a native command, you can use the `!` prefix. To exit the embedded shell, press `ctrl-c`. [[cli-install-uninstall]] === Adding Extensions to the CLI You can add extensions to the CLI by using the `install` command. The command takes one or more sets of artifact coordinates in the format `group:artifact:version`, as shown in the following example: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring install com.example:spring-boot-cli-extension:1.0.0.RELEASE ---- In addition to installing the artifacts identified by the coordinates you supply, all of the artifacts' dependencies are also installed. To uninstall a dependency, use the `uninstall` command. As with the `install` command, it takes one or more sets of artifact coordinates in the format of `group:artifact:version`, as shown in the following example: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE ---- It uninstalls the artifacts identified by the coordinates you supply and their dependencies. To uninstall all additional dependencies, you can use the `--all` option, as shown in the following example: [indent=0,subs="verbatim,quotes,attributes"] ---- $ spring uninstall --all ---- [[cli-groovy-beans-dsl]] == Developing Applications with the Groovy Beans DSL Spring Framework 4.0 has native support for a `beans{}` "`DSL`" (borrowed from https://grails.org/[Grails]), and you can embed bean definitions in your Groovy application scripts by using the same format. This is sometimes a good way to include external features like middleware declarations, as shown in the following example: [source,groovy,indent=0] ---- @Configuration(proxyBeanMethods = false) class Application implements CommandLineRunner { @Autowired SharedService service @Override void run(String... args) { println service.message } } import my.company.SharedService beans { service(SharedService) { message = "Hello World" } } ---- You can mix class declarations with `beans{}` in the same file as long as they stay at the top level, or, if you prefer, you can put the beans DSL in a separate file. [[cli-maven-settings]] == Configuring the CLI with settings.xml The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolve dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml` to configure Aether. The following configuration settings are honored by the CLI: * Offline * Mirrors * Servers * Proxies * Profiles ** Activation ** Repositories * Active profiles See https://maven.apache.org/settings.html[Maven's settings documentation] for further information. [[cli-whats-next]] == What to Read Next There are some {spring-boot-code}/spring-boot-project/spring-boot-cli/samples[sample groovy scripts] available from the GitHub repository that you can use to try out the Spring Boot CLI. There is also extensive Javadoc throughout the {spring-boot-cli-module-code}[source code]. If you find that you reach the limit of the CLI tool, you probably want to look at converting your application to a full Gradle or Maven built "`Groovy project`". The next section covers Spring Boot's "<>", which you can use with Gradle or Maven.