Need help with rest-shell?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

457 Stars 100 Forks Apache License 2.0 79 Commits 35 Opened issues


Command-line shell for interacting with Spring HATEOAS-compliant REST resources

Services available


Need anything else?

Contributors list

Spring HATEOAS-compliant REST shell

Installing the binaries

Using Homebrew:

    brew install rest-shell

Download the binary .tar.gz package:

    tar -zxvf rest-shell-1.2.0.RELEASE.tar.gz
    cd rest-shell-1.2.0.RELEASE

Building and Running

    git clone git://
    cd rest-shell
    ./gradlew installApp
    cd build/install/rest-shell-1.2.0.RELEASE

Getting Started

This project is a command-line shell that aims to make writing REST-based applications easier. It is based on spring-shell and integrated with Spring HATEOAS in such a way that REST resources that output JSON compliant with Spring HATEOAS can be discovered by the shell and interactions with the REST resources become much easier than by manipulating the URLs in bash using a tool like


The rest-shell provides a number of useful commands for discovering and interacting with REST resources. For example

will discover what resources are available and print out an easily-readable table of rels and URIs that relate to those resources. Once these resources have been discovered, the
of those URIs can be used in place of the URI itself in most operations, thus cutting down on the amount of typing needed to issue HTTP requests to your REST resources.

Discovering resources

The rest-shell is aimed at making it easier to interact with REST resources by managing the session

much like a directory in a filesystem. Whenever resources are
ed, you can then
to a new baseUri, which means you can then use relative URIs. Here's an example of discovering resources, then following a link by referencing its
value, and then using a relative URI to access resources under that new baseUri:
    http://localhost:8080:> discover
    rel                href
    address            http://localhost:8080/address
    family             http://localhost:8080/family
    people             http://localhost:8080/person
    profile            http://localhost:8080/profile

http://localhost:8080:> follow people
http://localhost:8080/person:> list
rel             href
people.Person    http://localhost:8080/person/1
people.Person    http://localhost:8080/person/2    http://localhost:8080/person/search

http://localhost:8080/person:> get 1
> GET http://localhost:8080/person/1

< 200 OK
< ETag: "2"
< Content-Type: application/json
    "links" : [ {
        "rel" : "self",
        "href" : "http://localhost:8080/person/1"
    }, {
        "rel" : "peeps.Person.profiles",
        "href" : "http://localhost:8080/person/1/profiles"
    }, {
        "rel" : "peeps.Person.addresses",
        "href" : "http://localhost:8080/person/1/addresses"
    } ],
    "name" : "John Doe"

NOTE: If you want tab completion of discovered rels, just use the


Creating new resources

The rest-shell can do basic parsing of JSON data within the shell (though there are some limitations due to the nature of the command line parsing being sensitive to whitespace). This makes it easy to create new resources by including JSON data directly in the shell:

    http://localhost:8080/person:> post --data "{name: 'John Doe'}"
    > POST http://localhost:8080/person/

< Location: http://localhost:8080/person/8
< Content-Length: 0

http://localhost:8080/person:> get 8
> GET http://localhost:8080/person/8

< 200 OK
< ETag: "0"
< Content-Type: application/json
    "links" : [ {
        "rel" : "self",
        "href" : "http://localhost:8080/person/8"
    }, {
        "rel" : "people.Person.addresses",
        "href" : "http://localhost:8080/person/8/addresses"
    }, {
        "rel" : "people.Person.profiles",
        "href" : "http://localhost:8080/person/8/profiles"
    } ],
    "name" : "John Doe"

If your needs of representing JSON get more complicated than what the spring-shell interface can handle, you can create a directory somewhere with

files in it, one file per entitiy, and use the
option to the
command. This will walk the directory and make a
request for each
file found.
http://localhost:8080/person:> post --from work/people_to_load
128 items uploaded to the server using POST.

You can also reference a specific file rather than an entire directory.

http://localhost:8080/person:> post --from work/people_to_load/someone.json
1 items uploaded to the server using POST.

Passing query parameters

If you're calling URLs that require query parameters, you'll need to pass those as a JSON-like fragment in the

parameter to the
commands. Here's an example of calling a URL that expects parameter input:
    http://localhost:8080/person:> get search/byName --params "{name: 'John Doe'}"

Outputing results to a file

It's not always desirable to output the results of an HTTP request to the screen. It's handy for debugging but sometimes you want to save the results of a request because they're not easily reproducible or any number of other equally valid reasons. All the HTTP commands take an

parameter that writes the results of an HTTP operation to the given file. For example, to output the above search to a file:
    http://localhost:8080/person:> get search/byName --params "{name: 'John Doe'}" --output by_name.txt
    >> by_name.txt

Sending complex JSON

Because the

uses the spring-shell underneath, there are limitations on the format of the JSON data you can enter directly into the command line. If your JSON is too complex for the simplistic limitations of the shell
parameter, you can simply load the JSON from a file or from all the files in a directory.

When doing a

, you can optionally pass the
parameter. The value of this parameter should either be a file or a directory. If the value is a directory, the shell will read each file that ends with
and make a POST or PUT with the contents of that file. If the parameter is a file, then the
will simpy load that file and POST/PUT that data in that individual file.

Shelling out to bash

One of the nice things about spring-shell is that you can directly shell out commands to the underlying terminal shell. This is useful for doing things like load a JSON file in an editor. For instance, assume I have the Sublime Text 2 command

in my path. I can then load a JSON file for editing from the rest-shell like this:
    http://localhost:8080/person:> ! subl test.json

I then edit the file as I wish. When I'm ready to POST that data to the server, I can do so using the

    http://localhost:8080/person:> post --from test.json
    1 items uploaded to the server using POST.

Setting context variables

Starting with rest-shell version 1.1, you can also work with context variables during your shell session. This is useful for saving settings you might reference often. The rest-shell now integrates Spring Expression Language support, so these context variables are usable in expressions within the shell.

Working with variables
    http://localhost:8080/person:> var set --name specialUri --value
    http://localhost:8080/person:> var get --name specialUri
    http://localhost:8080/person:> var list
        "responseHeaders" : {
            ... HTTP headers from last request
        "responseBody" : {
            ... Body from the last request
        "specialUri" : "",
        "requestUrl" : ... URL from the last request,
        "env" : {
            ... System properties and environment variables

The variables are accessible from SpEL expressions which are valid in a number of different contexts, most importantly in the

argument to the HTTP and discover commands, and in the
argument to the

Since the rest-shell is aware of environment variables and system properties, you can incorporate external parameters into your interaction with the shell. For example, to externally define a baseUri, you could set a system property before invoking the shell. The shell will incorporate anything defined in the

environment variable, so you could parameterize your interaction with a REST service.
    JAVA_OPTS="-DbaseUri=" rest-shell

http://localhost:8080:> discover #{env.baseUri}
rel                href
... resources for this URL>

Per-user shell initialization

The rest-shell supports a "dotrc" type of initialization by reading in all files found in the

directory and assuming they have shell commands in them. The rest-shell will execute these commands on startup. This makes it easy to set variables for commonly-used URIs or possibly set a
    echo "var set --name svcuri --value" > ~/.rest-shell/00-vars
    echo "discover #{svcuri}" > ~/.rest-shell/01-baseUri

> rest-shell

INFO: No resources found...
INFO: Base URI set to ''

 ___ ___  __ _____  __  _  _     _ _  __
| _ \ __/' _/_   _/' _/| || |   / / | \ \
| v / _|`._`. | | `._`.| >< |  / / /   > >
|_|_\___|___/ |_| |___/|_||_| |_/_/   /_/

Welcome to the REST shell. For assistance hit TAB or type "help".>

SSL Certificate Validation

If you generate a self-signed certificate for your server, by default the rest-shell will complain and refuse to connect. This is the default behavior of RestTemplate. To turn off certificate and hostname checking, use the

ssl validate --enabled false

HTTP Basic authentication

There is also a convenience command for setting an HTTP Basic authentication header. Use

auth basic --username user --password passwd
to set a username and password to base64 encode and place into the Authorization header that will be part of the current session's headers.

You can clear the authentication by using the

auth clear
command or by removing the Authorization header using the
headers clear


The rest-shell provides the following commands:

  • discover
    - Find out what resources are available at the given URI. If no URI is given, use the baseUri.
  • follow
    - Set the baseUri to the URI assigned to this given
    but do not discover resources.
  • list
    - Discover the resources available at the current baseUri.
  • baseUri
    - Set the base URI used for this point forward in the session. Relative URIs will be calculated relative to this setting.
  • headers set
    - Set an HTTP header by passing this command a
  • headers clear
    - Clear all HTTP headers set in this session.
  • headers list
    - Print out the currently-set HTTP headers for this session.
  • history list
    - List the URIs previously set as baseUris during this session.
  • history go
    - Jump to a URI by pulling one from the history.
  • var clear
    - Clear this shell's variable context.
  • var get
    - Get a variable in this shell's context.
  • var list
    - List variables currently set in this shell's context.
  • var set
    - Set a variable in this shell's context.
  • up
    - Traverse one level up in the URL hierarchy.
  • get
    - HTTP GET from the given path.
  • post
    - HTTP POST to the given path, passing JSON given in the
  • put
    - HTTP PUT to the given path, passing JSON given in the
  • delete
    - HTTP DELETE to the given path.
  • auth basic
    - Set an HTTP Basic authentication token for use in this session.
  • auth clear
    - Clear the Authorization header currently in use.
  • ssl validate
    - Disable certificate checking to work with self-signed certificates.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.