If you are familiar with groovy, you know what groovysh is. It's damn simple REPL (read, evaluate, print, loop) shell for evaluating
groovy code. And groovy-shell-server is full featured groovy shell inside your application.
How many times you are in situation when all you need is to call some method inside your application, but the only way to do it
is JMX or custom user interface (web page, for instance)? Groovy shell server allows you to run REPL shell inside your application
and work with it like you are using groovysh.
Groovy shell server uses groovysh API inside, so all features of groovysh (autocompletion, history etc.) are supported.
Just include following dependency in your pom.xml (latest version is shown by the Maven Central badge above):
<dependency>
<groupId>com.farpost</groupId>
<artifactId>groovy-shell</artifactId>
<version>LATEST_VERSION_FROM_BADGE</version>
</dependency>
- Java 17 or newer; CI covers Java 17, 21 and 25. Release artifacts are built on JDK 25 with Java 17 bytecode.
- Groovy 6.0.0 with its JLine 4 based shell.
- Spring integration uses Spring Framework 7.0.10 (optional).
- Logging uses SLF4J 2.0.20; the optional runtime backend is Logback 1.6.7.
This release supports Java 17 and newer. Earlier Groovy 6-based releases of this library required Java 25; use a newer release with Java 17 support when running on Java 17 or 21. Applications on Java 8 or 11 still need a runtime upgrade. The SSH transport uses Apache MINA SSHD 2.20.1 and the shell uses the Groovy 6/JLine 4 embedding API. Existing bindings, default scripts and SSH authentication remain supported; custom Groovy scripts should be checked against the Groovy 6 release notes.
Do not mix Groovy major versions on one classpath. Align all org.apache.groovy artifacts to 6.0.0 and remove older
org.codehaus.groovy artifacts; dependency management supplied by the host application may otherwise override these versions.
For Spring integration, align the application's Spring dependencies to the same major version. Applications that supply
their own logging implementation must use an SLF4J 2 compatible provider rather than an SLF4J 1.x binding.
The application ClassLoader is passed explicitly to the embedded Groovy engine so that SSH worker thread context does not determine which application classes the shell can see.
In your application you should start GroovyShellService:
GroovyShellService service = new GroovyShellService();
service.setPort(6789);
service.setBindings(new HashMap<String, Object>() {{
put("foo", obj1);
put("bar", obj2);
}});
service.start();
The shell uses the library's ClassLoader by default. Applications with a separate plugin or application loader can set it explicitly before starting the service:
service.setClassLoader(MyApplication.class.getClassLoader());
And destroy it on application exit:
service.destroy();
As of 1.5 Groovy shell server use plain ssh as a client. So connecting to a groovy shell server as simple as:
$ ssh 127.1 -p 6789
Groovy Shell (6.0.0)
Type ':help' or ':h' for help.
-------------------------------------------------------------------------------
groovy:000> (1..10).each { println "Kill all humans!" }
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
Kill all humans!
===> 1..10
groovy:000>
By default, no authentication is required (any username is allowed to open a SSH connection). You can enable password authentication by creating your own implementation of org.apache.sshd.server.auth.password.PasswordAuthenticator interface and passing an instance to server:
PasswordAuthenticator myPasswordAuthenticator = new MyPasswordAuthenticator();
service.setPasswordAuthenticator(myPasswordAuthenticator);
You can easily integrate Groovy Shell with Spring container:
<bean class="com.farpost.groovysh.spring.GroovyShellServiceBean"
p:port="6789"
p:launchAtStart="true"
p:publishContextBeans="true"
p:bindings-ref="bindings"/>
<u:map id="bindings">
<entry key="foo" value="bar"/>
</u:map>
When publishContextBeans is true all context beans are published to groovy shell context. So bean with id foo
will be available as foo in groovy shell. Also reference to the ApplicationContext is added to bindings implicitly
as ctx. So in shell you can get objects from container by id or type (e.g. ctx.getBean('id')).
It is also possible to enable password authentication by setting passwordAuthenticator property on GroovyShellServiceBean.
In order to simple run applications you can use maven-exec plugin:
./mvnw -f groovy-shell/pom.xml exec:java -Dexec.mainClass=com.farpost.groovysh.Main
Integration tests start a real server on a random port and drive groovysh over SSH:
./mvnw test
What if a well-meaning developer fires up a remote shell and accidentally executes a script which hammers the server? Fortunately, each GroovyShellService instance registers itself with the default MBeanServer and provides a "killAllClients" operation to kill any open client sockets and stop the associated client threads. Thus you can connect with jconsole or your favorite JMX frontend to resolve this issue if it arises.
The library is published to Maven Central via Sonatype Central Portal.
Publishing involves three independent mechanisms:
- Namespace verification — one-time DNS TXT record on
farpost.comproves ownership ofcom.farpostgroupId - GPG signing — every artifact is signed with a private key; Maven Central verifies signatures against public keys on keyservers
- Sonatype token — authenticates the upload to central.sonatype.com
-
Sonatype token. Log in to central.sonatype.com, go to Account, click "Generate User Token". Save the username and password — they are shown only once. Export them as environment variables before running deploy:
export SONATYPE_USERNAME=<token username> export SONATYPE_PASSWORD=<token password>The deploy uses a project-local
.mvn/settings.xmlthat reads these env vars — no need to edit~/.m2/settings.xml. -
GPG key. The signing key is stored in the
.keys/directory (gitignored). No system-level GPG import needed — the Makefile uses the localGNUPGHOMEdirectly.If setting up on a new machine, just copy the
.keys/directory from a teammate or from company secrets.
make deploy
This runs ./mvnw clean deploy -Prelease -s .mvn/settings.xml -Drevision=<calver> which:
- Generates a CalVer version (
YYYY.MM.DD.HHMM) — every release is unique, no manual version bumps - Compiles code and creates
.jar - Generates
-sources.jarand-javadoc.jar - Signs everything with GPG (
.ascfiles) - Uploads to Sonatype Central Portal
- Waits for validation and auto-publishes to Maven Central
The GitHub Actions workflow then creates a GitHub Release
with the same CalVer version and exact source commit. Release notes combine reviewed migration fragments with
GitHub's generated change list. Read the release's Breaking changes and Migration sections before upgrading.
Local make deploy publishes to Maven Central; GitHub Release creation is handled by the workflow.
| Parameter | Value |
|---|---|
| Owner | FarPost dev@farpost.com |
| Algorithm | RSA 4096 |
| Expires | 2028-03-26 (extend before expiry) |
| Keyservers | keyserver.ubuntu.com, keys.openpgp.org |
| Location | .keys/gpg-home/ (GNUPGHOME) |
To extend the key before expiry:
GNUPGHOME=.keys/gpg-home gpg --edit-key FarPost
> expire
> (set new expiry)
> save
GNUPGHOME=.keys/gpg-home gpg --keyserver keyserver.ubuntu.com --send-keys <KEY_ID>