Further updates to grails-shell-cli and grails-forge-cli documentation

jamesfredley · jamesfredley · commit 7efc7181cacc · 2025-06-17T20:45:52.000-04:00
diff --git a/grails-doc/src/en/guide/REST/restProfile.adoc b/grails-doc/src/en/guide/REST/restProfile.adoc
@@ -17,7 +17,7 @@ specific language governing permissions and limitations
 under the License.
 ////
 
-Since Grails 3.1, Grails supports a tailored profile for creating REST applications that provides a more focused set of dependencies and commands.
+Grails supports a tailored profile for creating REST applications that provides a more focused set of dependencies and commands.
 
 To get started with the REST profile using the Grails Shell CLI, create an application specifying `rest-api` as the name of the profile:
 
@@ -30,7 +30,7 @@ This will create a new REST application that provides the following features:
 
 * Default set of commands for creating and generating REST endpoints
 * Defaults to using JSON views for rendering responses (see the next section)
-* Fewer plugins than the default Grails plugin (no GSP, no Asset Pipeline, nothing HTML related)
+* Fewer plugins than the default Grails web profile (no GSP, no Asset Pipeline, nothing HTML related)
 
 You will notice for example in the `grails-app/views` directory that there are `*.gson` files for rendering the default index page and as well as any 404 and 500 errors.
 
@@ -44,7 +44,7 @@ $ grails generate-all my.api.Book
 
 Instead of CRUD HTML interface a REST endpoint is generated that produces JSON responses. In addition, the generated functional and unit tests by default test the REST endpoint.
 
-To generate a REST application using the Forge CLI (Grails 7), use the following:
+To generate a REST application using the Forge CLI, use the following:
 
 [source,console]
 ----
diff --git a/grails-doc/src/en/guide/commandLine/creatingProject.adoc b/grails-doc/src/en/guide/commandLine/creatingProject.adoc
@@ -17,29 +17,28 @@ specific language governing permissions and limitations
 under the License.
 ////
 
-Creating a project is the primary usage of the Forge CLI.
-
 [NOTE]
 ====
-The `create-app` and related commands are available in both the Grails Shell CLI and the Forge CLI.
+The `create-app` and related commands are available in both the Grails Shell CLI and the Grails Forge CLI.
 
-- To create a basic project using the default Shell CLI:  
+- To create a project using the default Grails Shell CLI:
 `$ grails create-app myapp`
 - To use Forge-specific options (such as `--java-version`, `--features`, etc.):  
 `$ grails -t forge create-app myapp`
 
-Use the Forge CLI only when you need advanced scaffolding options. Otherwise, the traditional Shell CLI is preferred and supports typical project creation.
 ====
 
+The primary command for creating a new project is `create-app`, which creates a standard Grails web application that communicates over HTTP. For other types of applications, see the documentation below.
+
+Creating a project is the primary usage of the Grails Forge CLI.  You can also generate an application with grails-shell, which uses profiles for generation.
+
 The `create-app` and other advanced scaffolding commands support extended options in Forge, which must be run using the following format:
 
 [source,console]
 ----
 $ ./grails -t forge create-app myapp
 ----
 
-You can generate an application with grails-shell, which uses profiles. The primary command for creating a new project is create-app, which creates a standard Grails web application that communicates over HTTP. For other types of applications, see the documentation below.
-
 After generating a project with Forge, switch to the created directory and use the default Grails shell CLI (`./grails`) to manage, run, test, and deploy your application.
 
 [cols="1,3,4a,8a"]
@@ -148,7 +147,7 @@ The "create-*" commands are used to produce a fundamental Grails project, allowi
 |
 [source,shell]
 ----
---java-version 11
+--java-version 21
 ----
 
 | -s, --servlet
diff --git a/grails-doc/src/en/guide/commandLine/gradleBuild/gradlePlugins.adoc b/grails-doc/src/en/guide/commandLine/gradleBuild/gradlePlugins.adoc
@@ -19,35 +19,32 @@ under the License.
 
 The `create-app` command is available in both the Grails Shell CLI and the Forge CLI.
 
-- Use `grails create-app myapp` to generate a default project using the Grails Shell CLI. This is the most common usage and supports standard application scaffolding.
+- Use `grails create-app myapp` to generate a default project using the Grails Shell CLI. This is the most common usage.
 - Use `grails -t forge create-app myapp` to access advanced application generation options such as `--jdk`, `--gorm`, and other Forge-only flags.
 
 The example below assumes you are using the Forge CLI, which is solely intended for **application generation**. It does not support running, building, or managing a Grails application.
 
-When you create a new project with the link:../ref/Command%20Line/create-app.html[create-app] command using Grails 7 and the Forge CLI (`grails -t forge create-app`), a default `build.gradle` is generated for you.
+When you create a new project with the link:../ref/Command%20Line/create-app.html[create-app] command in the Forge CLI (`grails -t forge create-app`), a default `build.gradle` is generated for you.
 
 [source,groovy]
 ----
 plugins {
     id "groovy"
-    id "org.apache.grails.gradle.grails-web"
-    id "org.apache.grails.gradle.grails-gsp"
-    id "com.github.erdi.webdriver-binaries"
     id "war"
     id "idea"
-    id "com.bertramlabs.asset-pipeline"
-    id "application"
     id "eclipse"
 }
+
+apply plugin: "asset-pipeline"
+apply plugin: "org.apache.grails.gradle.grails-web"
+apply plugin: "org.apache.grails.gradle.grails-gsp"
 ----
 
 The default plugins are as follows:
 
 * `groovy` - The Groovy plugin adds support for Groovy projects. It can handle Groovy code mixed with Java. Read More: https://docs.gradle.org/{gradleVersion}/userguide/groovy_plugin.html[The Groovy Plugin]
-* `com.github.erdi.webdriver-binaries` - A plugin that downloads and caches WebDriver binaries specific to the OS the build runs on. Read More: https://github.com/erdi/webdriver-binaries-gradle-plugin/blob/master/README.md[GitHub README]
 * `war` - The https://docs.gradle.org/{gradleVersion}/userguide/war_plugin.html[WAR plugin] changes the packaging so that Gradle creates a WAR file. You can comment out this plugin to build a runnable JAR file for standalone deployment.
 * `idea` - The IDEA plugin generates files used by http://www.jetbrains.com/idea/[IntelliJ IDEA], allowing the project to be opened from IDEA. Read More: https://docs.gradle.org/{gradleVersion}/userguide/idea_plugin.html[The IDEA Plugin]
-* `application` - The Application plugin facilitates creating an executable JVM application. Read More: https://docs.gradle.org/{gradleVersion}/userguide/application_plugin.html[The Application Plugin]
 * `eclipse` - The Eclipse plugins generate files for the http://eclipse.org/[Eclipse IDE], enabling project import (File - Import... - Existing Projects into Workspace). Read More: https://docs.gradle.org/{gradleVersion}/userguide/eclipse_plugin.html[The Eclipse Plugin]
 * `asset-pipeline` - The https://github.com/wondrify/asset-pipeline[Asset Pipeline] plugin enables compilation of static assets (JavaScript, CSS, etc.)
 
diff --git a/grails-doc/src/en/guide/commandLine/interactiveMode.adoc b/grails-doc/src/en/guide/commandLine/interactiveMode.adoc
@@ -40,18 +40,10 @@ Note that with ! (bang) commands, you get file path auto completion - ideal for
 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.
 
 
-With Grails Forge, when you execute the `grails` command without any arguments, the Grails Command Line Interface (CLI) enters interactive mode. In this mode, it functions like a shell, allowing you to run multiple CLI commands without the need to re-initialize the CLI runtime. This mode is particularly useful when working with code-generation commands (such as `create-controller`), creating multiple projects, or exploring various CLI features.
+With Grails Forge, when you execute the `grails -t forge` command, the Grails Command Line Interface (CLI) enters interactive mode. In this mode, it functions like a shell, allowing you to run multiple CLI commands without the need to re-initialize the CLI runtime. This mode is particularly useful when working with code-generation commands (such as `create-controller`), creating multiple projects, or exploring various CLI features.
 
 One of the advantages of interactive mode is the availability of tab-completion. You can simply press the TAB key to view possible options for a given command or flag. Here's an example of the available options in interactive mode:
 
-[NOTE]
-====
-The `create-app` command is available in both the Grails Shell CLI and the Forge CLI.
-
-- To run it using the traditional shell (Grails Shell CLI), simply use: `grails create-app myapp`
-- To access Forge-specific options such as `--java-version` and `--list-features`, use: `grails -t forge create-app myapp`
-====
-
 The Grails Shell CLI (`grails`) supports interactive tab-completion and most developer commands. However, advanced configuration flags are only available via the Forge CLI (`grails -t forge`).
 Here's an example of the available options in interactive mode:
 
@@ -68,7 +60,7 @@ You can access general usage information for Grails commands using the help flag
 
 [source,shell]
 ----
-grails create-app -h
+grails> create-app -h
 Usage: grails create-app [-hivVx] [--list-features] [-g=GORM Implementation] [--jdk=<javaVersion>]
                          [-s=Servlet Implementation] [-t=TEST] [-f=FEATURE[,FEATURE...]]... [NAME]
 Creates an application
@@ -100,21 +92,11 @@ Creates an application
   -x, --stacktrace      Show full stack trace when exceptions occur.
 ----
 
-[NOTE]
-====
-To view the full set of Forge-specific options for the `create-app` command, use `grails -t forge create-app -h`.
-This will show additional flags not available in the Grails Shell CLI.
-[source,shell]
-----
-grails -t forge create-app -h
-----
-====
-
 You can also obtain a list of available features by using the --list-features flag with any of the create commands.
 
 [source,shell]
 ----
-grails -t forge create-app --list-features
+grails> create-app --list-features
 Available Features
 (+) denotes the feature is included by default
   Name                                Description
diff --git a/grails-doc/src/en/guide/gettingStarted/aHelloWorldExample.adoc b/grails-doc/src/en/guide/gettingStarted/aHelloWorldExample.adoc
@@ -26,12 +26,12 @@ Navigate to the directory where you want to create your Grails project:
 [source,console]
 $ cd your_project_directory
 
-Create a new Grails 7 project with the following command:
+Create a new Grails project with the following command:
 
 [source,console]
 $ grails -t forge create-app myapp
 
-NOTE: If you're using Grails 6 or earlier, you can omit -t forge, but for Grails 7, -t forge is required to access the new CLI structure.
+NOTE: You can omit `-t forge`, to generate the application with Grails Shell CLI and profiles
 
 === Step 2: Access the Project Directory
 
@@ -42,10 +42,10 @@ $ cd myapp
 
 === Step 3: Start Grails Interactive Console
 
-Start the Grails interactive console by running the "grails" command:
+Start the Grails Forge CLI interactive console by running the "grails" command:
 
 [source,console]
-$ grails
+$ grails -t forge
 
 === Step 4: Create a Controller
 
diff --git a/grails-doc/src/en/guide/gettingStarted/creatingAnApplication.adoc b/grails-doc/src/en/guide/gettingStarted/creatingAnApplication.adoc
@@ -24,14 +24,16 @@ $ grails <<command name>>
 
 Run link:../ref/Command%20Line/create-app.html[create-app] to create an application:
 
+NOTE: The `create-app` command is supported by both the Grails Shell CLI and the Grails Forge CLI.
+
+Grails Shell CLI
 [source,console]
 $ grails create-app myapp
 
+Grails Forge CLI
 [source,console]
 $ grails -t forge create-app myapp
 
-NOTE: The `create-app` command is supported by both the Grails Shell CLI and the Forge CLI. Use `grails create-app` by default, as it is the most common and preferred usage. Only use `grails -t forge create-app` when you need Forge-specific options like `--java-version` or `--features`.
-
 This will create a new directory inside the current one that contains the project. Navigate to this directory in your console:
 
 [source,console]
diff --git a/grails-doc/src/en/guide/gettingStarted/creatingArtefacts.adoc b/grails-doc/src/en/guide/gettingStarted/creatingArtefacts.adoc
@@ -21,15 +21,25 @@ Grails provides a set of useful CLI commands for various tasks, including the cr
 
 For instance, to create the foundation of an application, you typically need to generate a domain model using Grails Commands:
 
+The `create-app` and `create-domain-class` commands are supported in both the Grails Shell CLI and the Grails Forge CLI.
+
+
+Grails Forge CLI
+[source,console]
+----
+$ grails -t forge create-app myapp
+$ cd myapp
+$ grails -t forge create-domain-class book
+----
+
+Grails Shell CLI
 [source,console]
 ----
 $ grails create-app myapp
 $ cd myapp
 $ grails create-domain-class book
 ----
 
-The `create-app` command is supported in both the Grails Shell CLI and the newer Forge CLI. Use the default `grails create-app` command with the Shell CLI unless you need Forge-specific options like `--java-version`, in which case you should run it with `grails -t forge create-app`.
-
 Executing these commands will result in the creation of a domain class located at `grails-app/domain/myapp/Book.groovy`, as shown in the following code:
 
 [source,groovy]
diff --git a/grails-doc/src/en/guide/gettingStarted/downloadingAndInstalling.adoc b/grails-doc/src/en/guide/gettingStarted/downloadingAndInstalling.adoc
@@ -41,7 +41,7 @@ Historically, this shell has not had autocompletion.
 By default, `./grails` uses `grails-shell-cli` for backwards compatibility.
 To use `grails-forge-cli`, pass the `-t` or `--type` argument:
 [source,console]
-$ ./grails -t forge create-app myapp
+$ ./grails -t forge
 
 
 === Install with SDKMAN
@@ -57,7 +57,7 @@ You can also specify a version
 $ sdk install grails {version}
 
 You can find more information about SDKMAN usage on the https://sdkman.io/usage[SDKMAN Docs].
-After installing, all three CLI commands—`grails`, `grails-shell-cli`, and `grails-forge-cli`—should be available.
+After installing, all three CLI commands: `grails`, `grails-shell-cli`, and `grails-forge-cli` will be available.
 
 === Manual installation
 
diff --git a/grails-doc/src/en/guide/gettingStarted/usingInteractiveMode.adoc b/grails-doc/src/en/guide/gettingStarted/usingInteractiveMode.adoc
@@ -23,7 +23,7 @@ Since 3.0, Grails has an interactive mode which makes command execution faster s
 
 image::interactive-output.png[]
 
-NOTE: As of **Grails 7**, both the Grails Shell CLI and the Forge CLI are available. Interactive mode is part of the Grails Shell CLI and is accessed by typing `grails` without additional arguments. Only use the `-t forge` flag when you need Forge-specific commands, such as `--java-version`.
+NOTE: As of **Grails 7**, both the Grails Shell CLI and the Forge CLI are available. Interactive mode is part of the Grails Shell CLI and is accessed by typing `grails` without additional arguments. Grails Forge CLI is accessed as `grails -t forge`.
 
 For more information on the capabilities of interactive mode refer to the section on link:commandLine.html#interactiveMode[Interactive Mode] in the user guide.
 
diff --git a/grails-doc/src/en/guide/plugins/creatingAndInstallingPlugins.adoc b/grails-doc/src/en/guide/plugins/creatingAndInstallingPlugins.adoc
@@ -20,21 +20,34 @@ under the License.
 
 ==== Creating Plugins
 
-// Not updated for Grails 7
 Creating a Grails plugin is a simple matter of running the command:
 
+Grails Shell CLI
 [source,groovy]
 ----
 grails create-plugin <<PLUGIN NAME>>
 ----
 
-This will create a web-plugin project for the name you specify. For example running `grails create-plugin example` would create a new web-plugin project called `example`.
+Grails Forge CLI
+[source,groovy]
+----
+grails -t forge create-plugin <<PLUGIN NAME>>
+----
 
-In Grails 3.0 you should consider whether the plugin you create requires a web environment or whether the plugin can be used with other profiles. If your plugin does not require a web environment then use the "plugin" profile instead of the default "web-plugin" profile:
+This will create a plugin project for the name you specify. For example running `grails create-plugin example` would create a new plugin project called `example`.
+
+You should consider whether the plugin you create requires a web environment or whether the plugin can be used with other profiles. If your plugin requires a web environment then use the "web-plugin" profile instead of the default "plugin" profile:
 
+Grails Shell CLI
 [source,groovy]
 ----
-grails create-plugin <<PLUGIN NAME>> --profile=plugin
+grails create-web-plugin <<PLUGIN NAME>>
+----
+
+Grails Forge CLI
+[source,groovy]
+----
+grails -t forge create-web-plugin <<PLUGIN NAME>>
 ----
 
 Make sure the plugin name does not contain more than one capital letter in a row, or it won't work. Camel case is fine, though.
diff --git a/grails-doc/src/en/guide/profiles/creatingProfiles.adoc b/grails-doc/src/en/guide/profiles/creatingProfiles.adoc
@@ -82,16 +82,16 @@ $ gradle install
 
 Your profile is now usable with the `create-app` command:
 
-[source,console]
+[source,bash]
 ----
-$ grails -t forge create-app myapp --profile mycompany
+$ grails create-app myapp --profile mycompany
 ----
 
 With the above command the application will be created with the "mycompany" profile which includes an additional dependency on the "myplugin" plugin and also includes the "hibernate" and "asset-pipeline" features (more on features later).
 
 Note that if you customize the dependency coordinates of the profile (group, version etc.) then you may need to use the fully qualified coordinates to create an application:
 
-[source,console]
+[source,bash]
 ----
-$ grails -t forge create-app myapp --profile com.mycompany:mycompany:1.0.1
+$ grails create-app myapp --profile com.mycompany:mycompany:1.0.1
 ----
diff --git a/grails-doc/src/en/guide/profiles/profileFeatures.adoc b/grails-doc/src/en/guide/profiles/profileFeatures.adoc
@@ -70,9 +70,9 @@ The contents of the skeleton get copied into the application tree, whilst the `a
 
 With the `feature.yml` you can define additional dependencies. This allows users to create applications with optional features. For example:
 
-[source,console]
+[source,bash]
 ----
-$ grails -t forge create-app myapp --profile myprofile --features myfeature,hibernate
+$ grails create-app myapp --profile myprofile --features myfeature,hibernate
 ----
 
 The above example will create a new application using your new feature and the "hibernate" feature.
diff --git a/grails-doc/src/en/guide/reference.adoc b/grails-doc/src/en/guide/reference.adoc
@@ -50,6 +50,7 @@ include::ref/Command Line/console.adoc[]
 
 include::ref/Command Line/create-app.adoc[]
 
+[[ref-command-line-create-command]]
 ==== create-command
 [[ref-command-line-assemble]]
 ==== assemble
diff --git a/grails-doc/src/en/guide/upgrading/upgrading50x.adoc b/grails-doc/src/en/guide/upgrading/upgrading50x.adoc
@@ -31,7 +31,6 @@ Please make sure to update your project's Java version to 11 before proceeding w
 
 Grails 6 comes with a completely revamped and highly efficient Command Line Interface (CLI) that enables you to generate applications and plugins at a remarkable speed. For instance, you can now use the new CLI to create a new Grails 6 application with the following command:
 
-
 ```bash
 grails create-app my-app
 ```
diff --git a/grails-doc/src/en/ref/Command Line/create-app.adoc b/grails-doc/src/en/ref/Command Line/create-app.adoc
@@ -83,7 +83,7 @@ Available flags:
 - `--features` _(limited support depending on profile)_
 - `--profile`
 
-Forge-only options such as `--jdk`, `--gorm`, or `--servlet` are **not supported** in the Shell CLI and will fail.
+Forge-only options such as `--jdk`, `--gorm`, or `--servlet` are **not supported** in the Shell CLI.
 
 === Examples
 
diff --git a/grails-doc/src/en/ref/Command Line/help.adoc b/grails-doc/src/en/ref/Command Line/help.adoc
@@ -98,7 +98,7 @@ From the terminal, run:
 
 [source,console]
 ----
-$grails --help
+grails> --help
 Usage: grails [-hvVx] [COMMAND]
 Grails CLI command line interface for generating projects and services.
 Application generation commands are:
@@ -133,7 +133,7 @@ NOTE: To access help for Forge-only options such as `--features`, `--jdk`, or `-
 
 [source,shell]
 ----
-$ grails -t forge create-app --help
+grails> create-app --help
 Usage: grails create-app [-hivVx] [--list-features] [-g=GORM Implementation] [--jdk=<javaVersion>]
                          [-s=Servlet Implementation] [-t=TEST] [-f=FEATURE[,FEATURE...]]... [NAME]
 Creates an application
