1. Groovy : Groovy Shell
| The groovysh is undergoing a major re-vamp and some of this information may not yet have been updated to reflect the latest changes. |
The Groovy Shell, aka. groovysh is a command-line application which
allows easy access to evaluate Groovy expressions, define classes and
run simple experiments.
1.1. Features
-
Rich cross-platform line editing, history and completion thanks to JLine3.
-
ANSI colors (prompt, exception traces, etc).
-
Simple, yet robust, command system with online help, user alias support and more.
-
User profile support
1.2. Command-line Options and Arguments
The shell supports several options to control verbosity, ANSI coloring and other features.
./bin/groovysh --help
Usage: groovysh [options] [...]
The Groovy Shell, aka groovysh, is a command-line application which allows easy
access to evaluate Groovy expressions, define classes and run simple
experiments.
-C, --color[=<FLAG>] Enable or disable use of ANSI colors
-cp, -classpath, --classpath
Specify where to find the class files - must be first
argument
-d, --debug Enable debug output
-D, --define=<name=value>
Define a system property
-e, --evaluate=<CODE> Evaluate the code first when starting interactive session
-h, --help Display this help message
-pa, --parameters Generate metadata for reflection on method parameter names
(jdk8+ only)
-pr, --enable-preview Enable preview Java features (jdk12+ only)
-q, --quiet Suppress superfluous output
-T, --terminal=<TYPE> Specify the terminal TYPE to use
-v, --verbose Enable verbose output
-V, --version Display the version
1.3. Evaluating Expressions
1.3.1. Simple Expressions
groovy> println "Hello"
Hello
1.3.2. Evaluation Result
When a complete expression is found, it is compiled and evaluated. The
result of the evaluation is stored into the _ variable.
1.3.3. Multi-line Expressions
Multi-line/complex expressions (like closure or class definitions) may be defined over several lines. When the shell detects that it has a complete expression it will compile and evaluate it.
Define a Class
You can define all the normal types, e.g. a class:
groovy> class Foo {
add: } > def bar() {
add: }}> println "baz"
add: }}> }
add: } > }
And use it in the normal way.
groovy> foo = new Foo()
groovy> foo.bar()
baz
Defined classes are known to the shell and can be used in completion:

1.3.4. Variables
Shell variables are all untyped (i.e. no def or other type information).
This will set a shell variable:
foo = "bar"
But, this will evaluate a local variable and will not be saved to the shell’s environment:
def foo = "bar"
This behavior can be changed by activating interpreter mode.
1.3.5. Methods
Methods can be defined in the shell, and will be saved for later use.
Defining a function is easy:
groovy> def hello(name) {
add: }> println("Hello $name")
add: }> }
And then using it is as one might expect:
groovy> hello "Jason"
Hello Jason
Internally the shell creates a closure to encapsulate the function and then binds the closure to a variable. So variables and functions share the same namespace.
1.4. Commands
The shell has a number of different commands, which provide rich access to the shell’s environment.
Commands all have a name and a shortcut (which is something like
/h). Commands may also have some predefined system aliases. Users
may also create their own aliases. This section will list commands in
alphabetical order, but you can also use the /help command to list
the available commands:
groovy> /help
/! execute shell command
/alias create command alias
/classloader display/manage Groovy classLoader data
/clear clear terminal
/colors view 256-color table and ANSI-styles
/console launch Groovy console
/del delete console variables, methods, classes and imports
/doc open document on browser
/echo echos a value
/grab add maven repository dependencies to classpath
/highlighter manage nanorc theme system
/history list history of commands
/imports show/delete import statements
/inspect display/browse object info on terminal/object browser
/keymap manipulate keymaps
/less file pager
/load load a file into the buffer
/methods show/delete methods
/nano edit files
/pipe create/delete pipe operator
/prnt print object
/reset clear the buffer
/save save the buffer to a file
/setopt set options
/setvar set lineReader variable value
/show list console variables
/ttop display and update sorted information about threads
/types show/delete types
/unalias remove command alias
/unsetopt unset options
/vars show/delete variable declarations
/widget manipulate widgets
/exit exit from app/script
/help command help
/slurp slurp file or string variable context to object
While in the interactive shell, you can ask for help for any command to
get more details about its syntax or function. You can use /help <command>
or <command> --help. Here is an example of
what happens when you ask for help for the /help command:
groovy> /help /help
help - command help
Usage: help [TOPIC...]
-? --help Displays command help
--groups Commands are grouped by registries
-i --info List commands with a short command info
1.4.1. /alias
Create an alias for a commandline fragment. The fragment could be Groovy code or a shell command. When evaluating a commandline, the alias will be replaced with the fragment:

The fragment is expected to be at the start of a line but other text may follow:

Aliases are persisted in a .groovysh/aliases.json file in the user home directory.
1.4.2. /classloader
Display and manage the Groovy classloader data.
Let’s /grab a dependency, define a class using it, and then use the /classloader command to see the classloader data:

1.4.3. /clear
Clears the screen.
1.4.4. /del
Deletes objects from the shell.
1.4.5. /echo
The /echo command outputs its arguments to the console. Arguments are output verbatim,
but variable expansion is also supported.

See also the /prnt command, which is similar but may perform additional formatting
on the output(s).
1.4.6. /exit
Exit the shell.
This is the only way to exit the shell. Well, you can still CTRL-Z on unix platforms,
but things like CTRL_C are trapped. (See JLine3 documentation for more details.)
1.4.7. /grab
Grab a dependency (Maven, Ivy, etc.) from Internet sources or cache, and add it to the Groovy Shell environment.
groovy> /grab org.apache.commons:commons-collections4:4.5.0
groovy> import org.apache.commons.collections4.bidimap.TreeBidiMap
groovy> TreeBidiMap t = [apple: 'red']
{apple=red}
groovy> t.inverseBidiMap()
{red=apple}
Completion is available. Currently, completion options are populated by known artifacts in the local Maven (~/.m2) and Grape (~/.groovy/grapes) repositories. In the future, completion from a remote repositories may be supported.
groovy> /grab org.apache.commons:commons-<TAB>
org.apache.commons:commons-collections4: org.apache.commons:commons-exec:
org.apache.commons:commons-compress: org.apache.commons:commons-imaging:
org.apache.commons:commons-configuration2: org.apache.commons:commons-lang3:
org.apache.commons:commons-crypto: org.apache.commons:commons-math3:
org.apache.commons:commons-csv: org.apache.commons:commons-parent:
org.apache.commons:commons-dbcp2: org.apache.commons:commons-pool2:
org.apache.commons:commons-digester3: org.apache.commons:commons-text:
org.apache.commons:commons-email:
This command can be given at any time to add new dependencies.
1.4.8. import
Add a custom import which will be included for all shell evaluations.
groovy> import java.util.concurrent.BlockingDeque
This command can be given at any time to add new imports.
Completion is available and prompts a level at a time using the package structure of all known classes.
groovy> import java.util.concurrent.<TAB>
others
atomic locks
Classes
AbstractExecutorService ConcurrentSkipListMap ForkJoinPool
ArrayBlockingQueue ConcurrentSkipListSet ForkJoinTask
...
Once an import statement has been executed, relevant classes will become available for completion:

1.4.9. /imports
You can use this to list and delete existing imports.
groovy> /imports
import java.util.concurrent.BlockingQueue
1.4.10. /inspect
Opens the GUI object browser to inspect a variable or the result of the last evaluation.
1.4.11. /less
Display the contents of a file (usually a page at a time). Formatting of common file types is supported.

1.4.12. /load
Load a file into the buffer.
If no filename is given as an argument, the current shared variables are
loaded from the .groovy/groovysh.ser file in the user home directory.
1.4.13. /nano
Edit the current buffer in an external editor.
Currently only works on UNIX systems which have the EDITOR environment
variable set, or have configured the editor preference.
1.4.14. /prnt
The /prnt command outputs its argument to the console. Both variable expansion
and formatting are supported.

See also the /echo command, which is similar but takes multiple arguments.
It also supports variable expansion but doesn’t support formatting.
1.4.15. /reset
Clears the current buffer and shared variables.
1.4.16. /save
Saves the buffer’s contents to a file.
If no filename is given as an argument, the current shared variables are
saved into the .groovy/groovysh.ser file in the user home directory.
1.4.17. /show
Show the shared variables (the binding).
1.4.18. /history
Display, manage and recall edit-line history.
history show
history recall
history flush
history clear
1.4.19. /doc
Opens a browser with documentation for the provided class.
For example, we can get both the Javadoc and GDK enhancements doc for java.util.List (shown running on JDK17):
groovy:000> :doc java.util.List https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html https://docs.groovy-lang.org/5.0.0-rc-1/html/groovy-jdk/java/util/List.html
This will print the documentation URLs found and open two windows (or tabs, depending on your browser):
-
one for the JDK documentation
-
one for the GDK documentation
By default, for Java classes, the java.base module is assumed. You can specify an optional module
for other cases (shown running on JDK17):
groovy:000> :doc java.scripting javax.script.ScriptContext https://docs.oracle.com/en/java/javase/17/docs/api/java.scripting/javax/script/ScriptContext.html
For backwards compatibility, if no module is specified when searching for Java classes, and no class is found in the java.base module, an additional attempt is made to find documentation for the class in the JDK8 (pre-module) Javadoc:
groovy:000> :doc javax.script.ScriptContext https://docs.oracle.com/javase/8/docs/api/javax/script/ScriptContext.html
To get the Groovydoc for groovy.ant.AntBuilder and groovy.xml.XmlSlurper:
groovy:000> :doc groovy.ant.AntBuilder https://docs.groovy-lang.org/5.0.0-rc-1/html/gapi/groovy/ant/AntBuilder.html groovy:000> :doc groovy.xml.XmlSlurper https://docs.groovy-lang.org/5.0.0-rc-1/html/gapi/groovy/xml/XmlSlurper.html
To get both the Groovydoc and GDK enhancements doc for groovy.lang.Closure and groovy.sql.GroovyResultSet:
groovy:000> :doc groovy.lang.Closure https://docs.groovy-lang.org/5.0.0-rc-1/html/gapi/groovy/lang/Closure.html https://docs.groovy-lang.org/5.0.0-rc-1/html/groovy-jdk/groovy/lang/Closure.html groovy:000> :doc groovy.sql.GroovyResultSet https://docs.groovy-lang.org/5.0.0-rc-1/html/gapi/groovy/sql/GroovyResultSet.html https://docs.groovy-lang.org/5.0.0-rc-1/html/groovy-jdk/groovy/sql/GroovyResultSet.html
Documentation is also available for the GDK enhancements to primitive arrays and arrays of arrays:
groovy:000> :doc int[] https://docs.groovy-lang.org/5.0.0-rc-1/html/groovy-jdk/primitives-and-primitive-arrays/int%5B%5D.html groovy:000> :doc double[][] https://docs.groovy-lang.org/5.0.0-rc-1/html/groovy-jdk/primitives-and-primitive-arrays/double%5B%5D%5B%5D.html
In contexts where opening a browser may not be desirable, e.g. on a CI server,
this command can be disabled by setting the groovysh.disableDocCommand system property to true.
|
1.4.20. set
Set or list preferences.
1.5. Preferences
Some aspects of groovysh behaviors can be customized by setting
preferences. Preferences are set using the set command or the :=
shortcut.
1.5.1. Recognized Preferences
interpreterMode
Allows the use of typed variables (i.e. def or other type information):
groovy:000> def x = 3 ===> 3 groovy:000> x ===> 3
It’s especially useful for copy&pasting code from tutorials etc. into the running session.
verbosity
Set the shell’s verbosity level. Expected to be one of:
-
DEBUG -
VERBOSE -
INFO -
QUIET
Default is INFO.
If this preference is set to an invalid value, then the previous setting will be used, or if there is none, then the preference is removed and the default is used.
editor
Configures the editor used by the edit command.
Default is the value of the system environment variable EDITOR.
To use TextEdit, the default text editor on macOS, configure: set editor /Applications/TextEdit.app/Contents/MacOS/TextEdit
1.5.2. Setting a Preference
groovy:000> :set verbosity DEBUG
1.5.3. Listing Preferences
To list the current set preferences (and their values):
groovy:000> :show preferences
Limitation: At the moment, there is no way to list all the known/available preferences to be set.
1.5.4. Clearing Preferences (i.e. Resetting to Defaults)
groovy:000> :purge preferences
1.6. User Profile Scripts and State
1.6.1. Profile Scripts
$HOME/.groovy/groovysh.profile
This script, if it exists, is loaded when the shell starts up.
$HOME/.groovy/groovysh.rc
This script, if it exists, is loaded when the shell enters interactive mode.
1.6.2. State
$HOME/.groovy/groovysh.history
Edit-line history is stored in this file.
1.7. Widgets
JLine provides a powerful widget system
that lets you extend the functionality of its line reader.
A number of builtin widgets are available including end-of-line, beginning-of-line, forward-word, backward-word, kill-word, backward-kill-word, capitalize-word, transpose-words, and yank-pop, just to name a few. You can use the /keymap command to see the key bindings for these widgets.
Groovy also includes JLine’s tailtip and autosuggest widget functionality.
You can see the related widgets by using the /widget -l command, which lists custom widgets.
groovy> /widget -l
_autosuggest-end-of-line (_autosuggest-end-of-line)
_autosuggest-forward-char (_autosuggest-forward-char)
_autosuggest-forward-word (_autosuggest-forward-word)
_tailtip-accept-line (_tailtip-accept-line)
_tailtip-backward-delete-char (_tailtip-backward-delete-char)
_tailtip-delete-char (_tailtip-delete-char)
_tailtip-expand-or-complete (_tailtip-expand-or-complete)
_tailtip-kill-line (_tailtip-kill-line)
_tailtip-kill-whole-line (_tailtip-kill-whole-line)
_tailtip-redisplay (_tailtip-redisplay)
_tailtip-self-insert (_tailtip-self-insert)
autosuggest-toggle (autosuggest-toggle)
tailtip-toggle (tailtip-toggle)
tailtip-window (tailtip-window)
These are available but not enabled by default.
You can enable them using the related toggle widgets. You can see what
key bindings
are associated with these widgets by using the /keymap command.
groovy> /keymap
...
"^[s" tailtip-toggle
"^[v" autosuggest-toggle
...
Normally, completions are shown when you hit the 'TAB' key, but with the tailtip widget enabled, you can see completions as you type., as well as additional usage information given in the tailtip window as seen here for a command:

And here for some code:

With the autosuggest widget enabled, you can see suggestions for what to type next as you type, based on your history, as seen here:

You can accept the entire suggestion or a word at a time. Both widgets can be enabled.
1.8. Custom commands
The register command allows you to register custom commands in the shell. For example, writing the following
will register the Stats command:
groovy:000> :register Stats
where the Stats class is a class extending the org.apache.groovy.groovysh.CommandSupport class. For example:
class Stats extends CommandSupport {
protected Stats(final Groovysh shell) {
super(shell, 'stats', 'T')
}
public Object execute(List args) {
println "Free memory: ${Runtime.runtime.freeMemory()}"
}
}
Then the command can be called using:
groovy:000> :stats stats Free memory: 139474880 groovy:000>
Note that the command class must be found on classpath: you cannot define a new command from within the shell.
1.8.1. Platform Problems
Problems loading the JLine DLL
On Windows, JLine2 (which is used for the fancy
shell input/history/completion fluff), uses a tiny DLL file to trick
the evil Windows faux-shell (CMD.EXE or COMMAND.COM) into
providing Java with unbuffered input. In some rare cases, this might
fail to load or initialize.
One solution is to disable the frills and use the unsupported terminal
instance. You can do that on the command-line using the --terminal
flag and set it to one of:
-
none -
false -
off -
jline.UnsupportedTerminal
groovysh --terminal=none
Problems with Cygwin on Windows
Some people have issues when running groovysh with cygwin. If you have troubles, the following may help:
stty -icanon min 1 -echo groovysh --terminal=unix stty icanon echo
2. GMavenPlus Maven Plugin
GMavenPlus is a Maven plugin with goals that support launching a Groovy Shell or Groovy Console bound to a Maven project.
3. Gradle Groovysh Plugin
Gradle Groovysh Plugin is a Gradle plugin that provides gradle tasks to start a Groovy Shell bound to a Gradle project.
