# Running Groovy from the commandline

version 6.0.0-RC-1

## 1. groovy, the Groovy command

`groovy` invokes the Groovy command line processor. It allows you to run inline Groovy expressions, and scripts, tests or application within groovy files. It plays a similar role to `java` in the Java world but handles inline scripts and rather than invoking class files, it is normally called with scripts and will automatically call the Groovy compiler as needed.

The easiest way to run a Groovy script, test or application is to run the following command at your shell prompt:

    > groovy MyScript.groovy

The `.groovy` part is optional. The `groovy` command supports a number of command line switches:

Short version | Long version | Description | Example
--- | --- | --- | ---
-a | --autosplit <splitPattern> | split lines using splitPattern (default '\s') using implicit 'split' variable |
-b | --basescript <class> | Base class name for scripts (must derive from Script) |
-c | --encoding <charset> | specify the encoding of the files |
-cp <path> | -classpath <path> --classpath <path> | Specify the compilation classpath. Must be the first argument. | groovy -cp lib/dep.jar MyScript
| --configscript <path> | Advanced compiler configuration script | groovy --configscript config/config.groovy src/Person.groovy
-D | --define <name=value> | define a system property |
-d | --debug | debug mode will print out full stack traces |
| --disableopt <optlist> | disables one or all optimization elements. optlist can be a comma separated list with the elements: all (disables all optimizations), int (disable any int based optimizations) |
-e <script> |  | specify an inline command line script | groovy -e "println new Date()"
-h | --help | Displays usage information for the command line groovy command | groovy --help
-i <extension> |  | modify files in place; create backup if extension is given (e.g. '.bak') |
-l <[host:]port> |  | listen on a port and process inbound lines (default: 1960); binds the loopback address unless a host is given | groovy -l 0.0.0.0:1960 -e "line.reverse()"
-n |  | process files line by line using implicit 'line' variable |
-p |  | process files line by line and print result (see also -n) |
-v | --version | display the Groovy and JVM versions | groovy -v
-pa | --parameters | Generates metadata for reflection on method parameter names on JDK 8 and above. Defaults to false. | groovy --parameters Person.groovy
-pr | --enable-preview | Enable preview Java features (jdk12+ only). | groovy --enable-preview Person.groovy

The `-l` option is a developer convenience for experimenting with a line-driven script, in the same spirit as `groovysh` but reading from a socket instead of a terminal. It is not an application server.

It runs the given script once for every line a client sends, with the line available as the implicit `line` variable and the connection as `out` and `socket`. The listening socket is bound to the loopback address, so only clients on the same machine can connect. Supply a host to listen more widely —`0.0.0.0:1960` for every interface, or a single address to pick one. The script is read once, when the listener starts, and recompiled for each connection so that one connection cannot leave state behind for the next; editing the file has no effect until the listener is restarted.

| A listener bound beyond loopback accepts connections from any peer that can reach the port. Groovy performs no authentication and the connection is not encrypted, so the script itself owns whatever checking is needed.

### 1.1. Configuring logging

Groovy’s command-line tools use JDK Platform Logging (`System.Logger`) for diagnostic messages. By default, this is backed by `java.util.logging` (JUL).

#### 1.1.1. Logging configuration file

JUL reads its configuration from exactly one source. The source is resolved in the following order:

1. The file specified by `-Djava.util.logging.config.file=…​` on the command line (via `JAVA_OPTS`).

2. The file `~/.groovy/logging.properties`, if it exists. Groovy automatically loads this at startup.

3. The JDK default at `$JAVA_HOME/conf/logging.properties`.

The first source found is used and the rest are ignored.

#### 1.1.2. Example configuration

    # ~/.groovy/logging.properties
    .level=INFO
    handlers=java.util.logging.ConsoleHandler
    java.util.logging.ConsoleHandler.level=ALL
    java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter
    java.util.logging.SimpleFormatter.format=%1$tT %4$s [%3$s] %5$s%6$s%n

    # Show Grape provider discovery details (or comment out for quieter operation)
    groovy.grape.Grape.level=FINE

#### 1.1.3. Logger reference

The following table lists all classes that emit log messages, grouped by module. The JUL level column shows the `java.util.logging` level to set in `logging.properties` (the Platform Logging level is shown in parentheses).

##### Core (`groovy`)

Logger name | JUL level | What is logged
--- | --- | ---
`groovy.grape.Grape` | FINE (DEBUG), WARNING, SEVERE (ERROR) | GrapeEngine provider discovery, selection, and instantiation failures
`groovy.ui.GroovyMain` | SEVERE (ERROR) | Script execution errors and uncaught exceptions
`org.apache.groovy.antlr.LexerFrame` | SEVERE (ERROR) | Parser errors in the lexer debugging tool
`org.codehaus.groovy.classgen.asm.OperandStack` | SEVERE (ERROR) | Stack operation errors during bytecode generation
`org.codehaus.groovy.classgen.asm.util.LoggableTextifier` | FINE (DEBUG) | ASM bytecode disassembly output
`org.codehaus.groovy.control.XStreamUtils` | FINE (DEBUG), WARNING | XStream serialization availability and failures
`org.codehaus.groovy.tools.DgmConverter` | INFO | DGM method stub generation progress
`org.codehaus.groovy.tools.FileSystemCompiler` | WARNING, SEVERE (ERROR) | Compilation errors and warnings
`org.codehaus.groovy.tools.GroovyStarter` | SEVERE (ERROR) | Startup configuration errors
`org.codehaus.groovy.tools.javac.JavacJavaCompiler` | INFO | Joint compilation progress

##### Grape Ivy (`groovy-grape-ivy`)

Logger name | JUL level | What is logged
--- | --- | ---
`groovy.grape.ivy` | INFO, FINE (DEBUG), FINEST (TRACE) | Ivy dependency resolution, downloads, and cache operations

##### Ant tasks (`groovy-ant`)

Logger name | JUL level | What is logged
--- | --- | ---
`org.codehaus.groovy.ant.Groovyc` | WARNING | Ant task compilation warnings
`org.codehaus.groovy.ant.Groovydoc` | WARNING | Ant task groovydoc warnings

##### Console (`groovy-console`)

Logger name | JUL level | What is logged
--- | --- | ---
`groovy.console.ui.ConsoleTextEditor` | WARNING | Text editor component warnings

##### GroovyDoc (`groovy-groovydoc`)

Logger name | JUL level | What is logged
--- | --- | ---
`org.codehaus.groovy.tools.groovydoc.FileOutputTool` | WARNING | File output warnings
`org.codehaus.groovy.tools.groovydoc.antlr4.GroovyDocParser` | WARNING | Doc parsing warnings
`org.codehaus.groovy.tools.groovydoc.GroovyDocTemplateEngine` | WARNING, SEVERE (ERROR) | Template processing errors
`org.codehaus.groovy.tools.groovydoc.GroovyRootDocBuilder` | WARNING | Doc building warnings

##### JSON (`groovy-json`)

Logger name | JUL level | What is logged
--- | --- | ---
`org.apache.groovy.json.internal.Exceptions` | SEVERE (ERROR) | JSON parsing exception details
`org.apache.groovy.json.internal.Sys` | WARNING | System property access warnings

##### Servlet (`groovy-servlet`)

Logger name | JUL level | What is logged
--- | --- | ---
`groovy.servlet.GroovyServlet` | SEVERE (ERROR) | Servlet script execution errors

##### Swing (`groovy-swing`)

Logger name | JUL level | What is logged
--- | --- | ---
`groovy.swing.table.TableSorter` | WARNING | Table sorting comparison warnings

##### Testing (`groovy-test`, `groovy-test-junit5`)

Logger name | JUL level | What is logged
--- | --- | ---
`groovy.test.GroovyTestSuite` | INFO | Test suite class loading info
`groovy.junit5.plugin.JUnit5Runner` | WARNING | JUnit5 runner warnings

| To enable all diagnostic logging, set `.level=FINE` in your configuration file. To focus on a specific area, set the logger name to `FINE` (or `FINER`/`FINEST` for trace-level detail) and leave the root level at `INFO` or `WARNING`.

| If a different `System.LoggerFinder` is on the classpath (e.g., via SLF4J/Logback or Log4j2), platform logging calls are routed to that backend instead, and `logging.properties` has no effect. Configure the alternative backend using its own mechanism (e.g., `logback.xml` or `log4j2.xml`).