////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

== create-command

=== Purpose


The `create-command` command creates a new Grails Gradle task and shell command that can be run with the `grails` command from a terminal window.

=== Examples

The command:

[source,groovy]
----
grails create-command MyExample
----

Creates a class called `grails-app/commands/PACKAGE_PATH/MyExampleCommand.groovy` such as:

[source,groovy]
----
import org.apache.grails.core.cli.*

class MyExampleCommand implements ApplicationCommand {

  boolean handle(ExecutionContext ctx) {
      def dataSource = applicationContext.getBean(DataSource)
      return true
  }
}
----

Commands can be executed with the `runCommand` command.

[source,java]
----
grails run-command my-example
----

Or as a Gradle task:

[source,java]
----
gradle runCommand -Pargs="myExample"
----

If the command you are executing is defined in a plugin that you have declared a dependency on, then you can execute the command in short form like so:

[source,groovy]
----
grails my-example
----

Or as a Gradle task:

[source,groovy]
----
gradle myExample
----

Declaring the plugin as a regular dependency is all that is required for the short form to work —
the plugin's companion `-cli` artifact (which carries its commands) is discovered from the
dependency graph automatically and both the command and its Gradle task are registered:

[source,groovy]
----
dependencies {
    implementation "org.grails.plugins:myplugin:0.1-SNAPSHOT"
}
----

=== Description

In order to separate the code generation and build layer, in Grails 3.x scripts created with `create-script` do not have access to the running application instance.

Instead, Grails 3.x features a new concept called an link:{apiFromRef}org/apache/grails/core/cli/ApplicationCommand.html[ApplicationCommand] that is invoked via Gradle to perform tasks such as interact with classes in the runtime.
