(Quick Reference)

5 The Command Line

Version: 4.1.0

5.1Interactive Mode

5.2Creating Custom Scripts

5.3Creating Custom Commands

5.4Re-using Grails scripts

5.5Building with Gradle

5.5.1Defining Dependencies with Gradle

5.5.2Working with Gradle Tasks

5.5.3Grails plugins for Gradle

5 The Command Line

Grails 3.0’s command line system differs greatly from previous versions of Grails and features APIs for invoking Gradle for build related tasks, as well as performing code generation.

When you type:

grails <<command name>>

Grails searches the profile repository based on the profile of the current application. If the profile is for a web application then commands are read from the web profile and the base profile which it inherits from.

Since command behavior is profile specific the web profile may provide different behavior for the run-app command then say a profile for running batch applications.

When you type the following command:

grails run-app

It will first search the application, and then the profile for commands:

PROJECT_HOME/src/main/scripts/run-app.groovy
[profile]/commands/run-app.groovy
[profile]/commands/run-app.yml

To get a list of all commands and some help about the available commands type:

grails help

which outputs usage instructions and the list of commands Grails is aware of:

grails <<environment>>* <<target>> <<arguments>>*'

| Examples:
$ grails dev run-app
$ grails create-app books

| Available Commands (type grails help 'command-name' for more info):
| Command Name                          Command Description
----------------------------------------------------------------------------------------------------
clean                                   Cleans a Grails application's compiled sources
compile                                 Compiles a Grails application
...

Refer to the Command Line reference in the Quick Reference menu of the reference guide for more information about individual commands

Arguments

The grails command is a front to a gradle invocation, because of this there can be unexpected side-effects. For example, when executing grails -Dapp.foo=bar run-app the app.foo system property won’t be available to your application. This is because bootRun in your build.gradle configures the system properties. To make this work you can simply append all System.properties to bootRun in build.gradle like:

bootRun{
    systemProperties System.properties // Please note not to use '=', because this will override all configured systemProperties. This will append them.
}

Or if you only want to pass through a limited set, you can prefix your system properties using an arbitrary prefix and configure bootRun like:

bootRun{
    bootRun {
        systemProperties System.properties.inject([:]){acc,item-> item.key.startsWith('boot.')?acc << [(item.key.substring('boot.'.length())):item.value]:acc }
    }
}

In this example only system properties starting with boot. are passed through.

Application and JVM arguments should be specified in bootRun as well.

bootRun{
    bootRun {
        jvmArgs('-Dspring.output.ansi.enabled=always')
        args('--app.foo=bar','--app.bar=foo') // Override the `app.foo` and `app.bar` config options (`grailsApplication.config`)
    }
}

non-interactive mode

When you run a script manually and it prompts you for information, you can answer the questions and continue running the script. But when you run a script as part of an automated process, for example a continuous integration build server, there’s no way to "answer" the questions. So you can pass the \--non-interactive switch to the script command to tell Grails to accept the default answer for any questions, for example whether to install a missing plugin.

For example:

grails war --non-interactive

5.1 Interactive Mode

Interactive mode is a feature of the Grails command line which keeps the JVM running and allows for quicker execution of commands. To activate interactive mode type 'grails' at the command line and then use TAB completion to get a list of commands:

If you need to open a file whilst within interactive mode you can use the open command which will TAB complete file paths:

Even better, the open command understands the logical aliases 'test-report' and 'dep-report', which will open the most recent test and dependency reports respectively. In other words, to open the test report in a browser simply execute open test-report. You can even open multiple files at once: open test-report test/unit/MyTests.groovy will open the HTML test report in your browser and the MyTests.groovy source file in your text editor.

TAB completion also works for class names after the create-* commands:

If you need to run an external process whilst interactive mode is running you can do so by starting the command with a !:

Note that with ! (bang) commands, you get file path auto completion - ideal for external commands that operate on the file system such as 'ls', 'cat', 'git', etc.

To exit interactive mode enter the exit command. Note that if the Grails application has been run with run-app normally it will terminate when the interactive mode console exits because the JVM will be terminated. An exception to this would be if the application were running in forked mode which means the application is running in a different JVM. In that case the application will be left running after the interactive mode console terminates. If you want to exit interactive mode and stop an application that is running in forked mode, use the quit command. The quit command will stop the running application and then close interactive mode.

5.2 Creating Custom Scripts

You can create your own Command scripts by running the create-script command from the root of your project. For example the following command will create a script called src/main/scripts/hello-world.groovy:

grails create-script hello-world

In general Grails scripts should be used for scripting the Gradle based build system and code generation. Scripts cannot load application classes and in fact should not since Gradle is required to construct the application classpath.

See below for an example script that prints "Hello World":

description "Example description", "grails hello-world"

println "Hello World"

The description method is used to define the output seen by grails help and to aid users of the script. The following is a more complete example of providing a description taken from the generate-all command:

description( "Generates a controller that performs CRUD operations and the associated views" ) {
  usage "grails generate-all <<DOMAIN CLASS>>"
  flag name:'force', description:"Whether to overwrite existing files"
  argument name:'Domain Class', description:'The name of the domain class'
}

As you can see this description profiles usage instructions, a flag and an argument. This allows the command to be used as follows:

grails generate-all MyClass --force

Template Generation

Plugins and applications that need to define template generation tasks can do so using scripts. A example of this is the Scaffolding plugin which defines the generate-all and generate-controllers commands.

Every Grails script implements the TemplateRenderer interface which makes it trivial to render templates to the users project workspace.

The following is an example of the create-script command written in Groovy:

description( "Creates a Grails script" ) {
  usage "grails create-script <<SCRIPT NAME>>"
  argument name:'Script Name', description:"The name of the script to create"
  flag name:'force', description:"Whether to overwrite existing files"
}

def scriptName = args[0]
def model = model(scriptName)
def overwrite = flag('force') ? true : false

render  template: template('artifacts/Script.groovy'),
        destination: file("src/main/scripts/${model.lowerCaseName}.groovy"),
        model: model,
        overwrite: overwrite

If a script is defined in a plugin or profile, the template(String) method will search for the template in the application before using the template provided by your plugin or profile. This allows users of your plugin or profile to customize what gets generated.

It is common to provide an easy way to allow users to copy the templates from your plugin or profile. Here is one example on how the angular scaffolding copies templates.

templates("angular/**/*").each { Resource r ->
    String path = r.URL.toString().replaceAll(/^.*?META-INF/, "src/main")
    if (path.endsWith('/')) {
        mkdir(path)
    } else {
        File to = new File(path)
        SpringIOUtils.copy(r, to)
        println("Copied ${r.filename} to location ${to.canonicalPath}")
    }
}

The "model"

Executing the model method with a Class/String/File/Resource will return an instance of Model. The model contains several properties that can help you generate code.

Example:

def domain = model(com.foo.Bar)

domain.className == "FooBar"
domain.fullName == "com.foo.FooBar"
domain.packageName == "com.foo"
domain.packagePath == "com/foo"
domain.propertyName == "fooBar"
domain.lowerCaseName == "foo-bar"

In addition, an asMap method is available to turn all of the properties into a map to pass to the render method.

Working with files

All scripts have access to methods on the FileSystemInteraction class. It contains helpful methods to copy, delete, and create files.

5.3 Creating Custom Commands

You can create your own commands by running the create-command command from the root of your project. For example the following command will create a command called grails-app/commands/HelloWorldCommand:

grails create-command HelloWorld

Unlike scripts, commands cause the Grails environment to start and you have full access to the application context and the runtime.

Since Grails 3.2.0, commands have similar abilities as scripts in regards to retrieving arguments, template generation, file access, and model building.

If you created a command in a previous version of grails, you can update your command to have those abilities by changing which trait you are implementing.

Commands created in Grails 3.1.x or lower implement the ApplicationCommand trait by default which requires your command to implement the following method:

boolean handle(ExecutionContext executionContext)

Commands created in Grails 3.2.0 or higher implement the GrailsApplicationCommand trait by default which requires your command to implement the following method:

boolean handle()

Commands defined this way still have access to the execution context via a variable called "executionContext".

Custom commands can be executed using grails run-command:

grails run-command my-example

Commands can also be executed using the runCommand gradle task. Note that the gradle task uses camelCase:

gradle runCommand -Pargs="my-example"

If the grails server is a subproject (e.g., in a project created with the angular profile), the subproject command can still be invoked from the gradle wrapper in the parent project:

./gradlew server:runCommand -Pargs="my-example"

5.4 Re-using Grails scripts

Grails ships with a lot of command line functionality out of the box that you may find useful in your own scripts (See the command line reference in the reference guide for info on all the commands).

Any script you create can invoke another Grails script simply by invoking a method:

testApp()

The above will invoke the test-app command. You can also pass arguments using the method arguments:

testApp('--debug-jvm')

Invoking Gradle

Instead of invoking another Grails CLI command you can invoke Gradle directory using the gradle property.

gradle.compileGroovy()

Invoking Ant

You can also invoke Ant tasks from scripts which can help if you need to writing code generation and automation tasks:

ant.mkdir(dir:"path")

5.5 Building with Gradle

Grails 3.1 uses the Gradle Build System for build related tasks such as compilation, runnings tests and producing binary distributions of your project. It is recommended to use Gradle 2.2 or above with Grails 3.1.

The build is defined by the build.gradle file which specifies the version of your project, the dependencies of the project and the repositories where to find those dependencies (amongst other things).

When you invoke the grails command the version of Gradle that ships with Grails 3.1 (currently 2.9) is invoked by the grails process via the Gradle Tooling API:

# Equivalent to 'gradle classes'
$ grails compile

You can invoke Gradle directly using the gradle command and use your own local version of Gradle, however you will need Gradle 2.2 or above to work with Grails 3.0:

$ gradle assemble

5.5.1 Defining Dependencies with Gradle

Dependencies for your project are defined in the dependencies block. In general you can follow the Gradle documentation on dependency management to understand how to configure additional dependencies.

The default dependencies for the "web" profile can be seen below:

dependencies {
  compile 'org.springframework.boot:spring-boot-starter-logging'
  compile('org.springframework.boot:spring-boot-starter-actuator')
  compile 'org.springframework.boot:spring-boot-autoconfigure'
  compile 'org.springframework.boot:spring-boot-starter-tomcat'
  compile 'org.grails:grails-dependencies'
  compile 'org.grails:grails-web-boot'

  compile 'org.grails.plugins:hibernate'
  compile 'org.grails.plugins:cache'
  compile 'org.hibernate:hibernate-ehcache'

  runtime 'org.grails.plugins:asset-pipeline'
  runtime 'org.grails.plugins:scaffolding'

  testCompile 'org.grails:grails-plugin-testing'
  testCompile 'org.grails.plugins:geb'

  // Note: It is recommended to update to a more robust driver (Chrome, Firefox etc.)
  testRuntime 'org.seleniumhq.selenium:selenium-htmlunit-driver:2.44.0'

  console 'org.grails:grails-console'
}

Note that version numbers are not present in the majority of the dependencies. This is thanks to the dependency management plugin which configures a Maven BOM that defines the default dependency versions for certain commonly used dependencies and plugins:

dependencyManagement {
    imports {
        mavenBom 'org.grails:grails-bom:' + grailsVersion
    }
    applyMavenExclusions false
}

5.5.2 Working with Gradle Tasks

As mentioned previously the grails command uses an embedded version of Gradle and certain Grails commands that existed in previous versions of Grails map onto their Gradle equivalents. The following table shows which Grails command invoke which Gradle task:

Grails Command

Gradle Task

clean

compile

classes

package

assemble

run-app

bootRun

test-app

test

test-app --integration

integrationTest

war

assemble

You can invoke any of these Grails commands using their Gradle equivalents if you prefer:

$ gradle test

Note however that you will need to use a version of Gradle compatible with Grails 3.1 (Gradle 2.2 or above). If you wish to invoke a Gradle task using the version of Gradle used by Grails you can do so with the grails command:

$ grails gradle compileGroovy

However, it is recommended you do this via interactive mode, as it greatly speeds up execution and provides TAB completion for the available Gradle tasks:

$ grails
| Enter a command name to run. Use TAB for completion:
 grails> gradle compileGroovy
 ...

To find out what Gradle tasks are available without using interactive mode TAB completion you can use the Gradle tasks task:

gradle tasks

5.5.3 Grails plugins for Gradle

When you create a new project with the create-app command, a default build.gradle is created. The default build.gradle configures the build with a set of Gradle plugins that allow Gradle to build the Grails project:

apply plugin:"war"
apply plugin:"org.grails.grails-web"
apply plugin:"org.grails.grails-gsp"
apply plugin:"asset-pipeline"

The default plugins are as follows:

war - The WAR plugin changes the packaging so that Gradle creates as WAR file from your application. You can comment out this plugin if you wish to create only a runnable JAR file for standalone deployment.
asset-pipeline - The asset pipeline plugin enables the compilation of static assets (JavaScript, CSS etc.)

Many of these are built in plugins provided by Gradle or third party plugins. The Gradle plugins that Grails provides are as follows:

org.grails.grails-core - The primary Grails plugin for Gradle, included by all other plugins and designed to operate with all profiles.
org.grails.grails-gsp - The Grails GSP plugin adds precompilation of GSP files for production deployments.
org.grails.grails-doc - A plugin for Gradle for using Grails 2.0’s documentation engine.
org.grails.grails-plugin - A plugin for Gradle for building Grails plugins.
org.grails.grails-plugin-publish - A plugin for publishing Grails plugins to the central repository.
org.grails.grails-profile - A plugin for use when creating Grails Profiles.
org.grails.grails-profile-publish - A plugin for publishing Grails profiles to the central repository.
org.grails.grails-web - The Grails Web gradle plugin configures Gradle to understand the Grails conventions and directory structure.

<< 4Configuration

6Application Profiles >>

5 The Command Line

Table of Contents

5 The Command Line

Arguments

non-interactive mode

5.1 Interactive Mode

5.2 Creating Custom Scripts

Template Generation

The "model"

Working with files

5.3 Creating Custom Commands

5.4 Re-using Grails scripts

Invoking Gradle

Invoking Ant

5.5 Building with Gradle

5.5.1 Defining Dependencies with Gradle

5.5.2 Working with Gradle Tasks

5.5.3 Grails plugins for Gradle

Command Line

Constraints

Controllers

Database Mapping

Domain Classes

Plug-ins

Services

Servlet API