jamesfredley commented on code in PR #14906: URL: https://github.com/apache/grails-core/pull/14906#discussion_r2206161224
########## grails-doc/src/en/guide/gettingStarted/downloadingAndInstalling.adoc: ########## @@ -21,16 +21,48 @@ There are many ways to create a Grails application. The best way is to use either https://start.grails.org[start.grails.org] or use the Grails CLI via https://sdkman.io[SDKMAN]. SDKMAN greatly simplifies installing and managing multiple Grails versions. -=== Types of CLI - -Historically, Grails had one CLI - `grails shell`. -In Grails 6, a new CLI was introduced `grails forge` that was meant to replace `grails shell`. -Unfortunately, IntelliJ's Grails plugin relies on the legacy shell to provide functions for the IDE. -For this reason, the decision was made to restore publishing of the `grails-shell` in later versions of Grails 6. The other problem is to customize application generation, `grails forge` would need to be forked, customized, published, and hosted somewhere. -The process of building and hosting a custom version of `grails-forge` was found to be cumbersome for some people because the previous shell allowed for customization by providing a directory that laid out a skeleton of what to create. -Worse, some critical plugins, such as the database migration plugin had custom commands that cannot be easily imported into the forge cli. - -For this reason, Grails 7 adds the following commands to any Grails install: +=== Types of command-line interface (CLI) + +Historically, Grails had one CLI - `grails shell`, until `grails forge` was introduced in Grails 6. + +==== Grails Shell CLI +The historical `grails shell` CLI has been a core part of the Grails Framework since its inception, providing command-line tools for project creation, code generation, and application management. +Nearly all historical references to the `grails` or `grailsw` commands pertain to `grails shell` functionality. +The `grails shell` CLI relies on Profiles, consisting of skeleton directories and YAML-based configurations for application generation. +However, this approach is less flexible than the feature-rich application generation capabilities of `grails forge`. +The Grails Wrapper is a lightweight script (`grailsw`) and accompanying JAR file designed to bootstrap and load the CLI within a Grails Application. +The `grails shell` CLI provides most of the same application generation functionality provided by `grails forge`. +Importantly, it can also run scripts, such as `run-app` that call Gradle and/or your Grails Application. +Most Grails plugins still include Grails Scripts that execute within `grails shell` CLI and have not yet been migrated to Gradle tasks. +IntelliJ IDEA's Grails plugin depends on `grails shell` for code generation and Grails command execution. +Extending application generation in the grails shell CLI is straightforward: developers can create a Custom Profile and reference it as a Maven dependency, which is generally simpler than customizing `grails forge`. + +==== Restoration of Grails Shell CLI +In Grails 6.0.0, `grails shell` CLI was removed and replaced with `grails forge` CLI. +However, in Grails 6.2.1, the grails shell CLI, along with Grails Profiles and the Wrapper were restored, empowering users to choose their preferred CLI and reclaiming functionalities that had not yet been fully transitioned to the `grails forge` CLI combined with Gradle tasks. + +==== Grails Shell CLI and Gradle +Certain CLI features overlap between `grails shell` CLI and Gradle. + +For Gradle these use the `runCommand` task, IE. `./gradlew runCommand -Pargs="generate-all org.bookstore.Author"` or custom Gradle tasks, such as `./gradlew dbmGormDiff` for the database migration plugin. Review Comment: I think this should include examples from common plugins, like scaffolding and database migration, but wanted to limit it to 10 or less, since it is not the right location for a definitive list. I've updated this to a table and added a few additional, common examples. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@grails.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
