Skip to end of metadata
Go to start of metadata

Groovy Shell

The Groovy Shell, aka. groovysh is a command-line application which allows easy access to evaluate Groovy expressions, define classes and run simple experiments.


  • No need for go command to execute buffer.
  • Rich cross-platform edit-line editing, history and completion thanks to JLine2.
  • ANSI colors (prompt, exception traces, etc).
  • Simple, yet robust, command system with online help, user alias support and more.
  • User profile support

Command-line Options and Arguments

The shell supports several options to control verbosity, ANSI coloring and other features.

./bin/groovysh --help
usage: groovysh [options] [...]
  -C, --color[=FLAG]         Enable or disable use of ANSI colors
  -D, --define=NAME=VALUE    Define a system property
  -T, --terminal=TYPE        Specify the terminal TYPE to use
  -V, --version              Display the version
  -classpath                 Specify where to find the class files - must
                             be first argument
  -cp, --classpath           Aliases for '-classpath'
  -d, --debug                Enable debug output
  -h, --help                 Display this help message
  -q, --quiet                Suppress superfluous output
  -v, --verbose              Enable verbose output

Evaluating Expressions

Simple Expressions

println "Hello"

Evaluation Result

When a complete expression is found, it is compiled and evaluated. The result of the evaluation is stored into the _ variable.

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
class Foo {
    def bar() {
        println "baz"
Use the Class
foo = new Foo()


Shell variables are all untyped (ie. 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"


Functions can be defined in the shell, and will be saved for later use.

Defining a function is easy:

groovy:000> def hello(name) {
groovy:001> println("Hello $name")
groovy:002> }

And then using it is as one might expect:


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.


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.

Recognized Commands


Display the list of commands (and aliases) or the help text for specific command.

The Command List
groovy:000> :help

For information about Groovy, visit:

Available commands:
  :help      (:h ) Display this help message
  ?          (:? ) Alias to: :help
  :exit      (:x ) Exit the shell
  :quit      (:q ) Alias to: :exit
  import     (:i ) Import a class into the namespace
  :display   (:d ) Display the current buffer
  :clear     (:c ) Clear the buffer and reset the prompt counter.
  :show      (:S ) Show variables, classes or imports
  :inspect   (:n ) Inspect a variable or the last result with the GUI object browser
  :purge     (:p ) Purge variables, classes, imports or preferences
  :edit      (:e ) Edit the current buffer
  :load      (:l ) Load a file or URL into the buffer
  .          (:. ) Alias to: :load
  :save      (:s ) Save the current buffer to a file
  :record    (:r ) Record the current session to a file
  :history   (:H ) Display, manage and recall edit-line history
  :alias     (:a ) Create an alias
  :set       (:= ) Set (or list) preferences
  :register  (:rc) Registers a new command with the shell
  :doc       (:D ) Opens a browser window displaying the doc for the argument
For help on a specific command type:
    :help command
Help for a Command

While in the interactive shell, you can ask for help for any command to get more details about its syntax or function. Here is an example of what happens when you ask for help for the help command:

groovy:000> :help :help

usage: help [<command>]

Display the list of commands or the help text for <command>.


Exit the shell.

This is the only way to exit the shell. Well, you can still CTRL-C, but the shell will complain about an abnormal shutdown of the JVM.


Add a custom import which will be included for all shell evaluations.

This command can be given at any time to add new imports.


Display the contents of the current buffer.

This only displays the buffer of an incomplete expression. Once the expression is complete, the buffer is rest. The prompt will update to show the size of the current buffer as well.

groovy:000> class Foo {
groovy:001> def bar
groovy:002> def baz() {
groovy:003> display
 001> class Foo {
 002> def bar
 003> def baz() {


Clears the current buffer, resetting the prompt counter to 000. Can be used to recover from compilation errors.


Show variables, classes or preferences or imports.

:show variables
groovy:000> :show variables
  _ = true
:show classes
:show imports
:show preferences
:show all


Opens the GUI object browser to inspect a variable or the result of the last evaluation.


Purges objects from the shell.

:purge variables
:purge classes
:purge imports
:purge preferences
:purge all


Edit the current buffer in an external editor.

Edit requires the EDITOR environment variable to be set, or the editor preference to be configured.


Load one or more files (or urls) into the buffer.


Saves the buffer's contents to a file.


Record the current session to a file.

:record start
:record stop
:record status


Display, manage and recall edit-line history.

:history show
:history recall
:history flush
:history clear


Create an alias.


Set or list preferences.


Opens a browser window displaying the doc for the argument.


groovy:000> :doc java.util.List


Some of aspects of groovysh behaviors can be customized by setting preferences. Preferences are set using the set command or the \= shortcut.

Recognized Preferences


Set the shell's verbosity level. Expected to be one of:

  • INFO

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.


Show the last result after an execution.

Default is true.


Sanitize (trim-down/filter) stack traces.

Default is true.


Configures the editor used by the edit command.

Default is the value of the system environment variable EDITOR.

Mac OS X


To use TextEdit, the default text editor on Mac OS X, configure:

:set editor /Applications/

Setting a Preference

:set verbosity DEBUG

Listing Preferences

To list the current set preferences (and their values):

:show preferences



At the moment, there is no way to list all of the known/available preferences to be set.

Clearing Preferences (i.e. Resetting to Defaults)

:purge preferences

User Profile Scripts and State

Profile Scripts


This script, if it exists, is loaded when the shell starts up.


This script, if it exists, is loaded when the shell enters interactive mode.



Edit-line history is stored in this file.


Please report any problems you run into. Please be sure to mark the JIRA issue with the Groovysh component.

Platform Problems

Problems loading the JLine DLL

On Windows, JLine (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
  • No labels