Intro to Vert.x Shell

Vert.x Shell pro­vides an ex­ten­si­ble com­mand line for Vert.x, ac­ces­si­ble via SSH, Tel­net or a nice Web in­ter­face. Vert.x Shell comes out of the box with plenty of com­mands for Vert.x which makes it very handy for doing sim­ple man­age­ment op­er­a­tions like de­ploy­ing a Ver­ti­cle or get­ting the list of de­ployed Ver­ti­cles. One power fea­ture of Vert.x Shell is its ex­ten­si­bil­ity: one can eas­ily aug­ment Vert.x Shell with its own com­mands. Let’s build an http-​client in JavaScript!

Booting the Shell

Vert.x Shell can be started in a cou­ple of lines de­pend­ing on the con­nec­tors you con­fig­ure. The doc­u­men­ta­tion pro­vides sev­eral ex­am­ples show­ing the Shell Ser­vice con­fig­u­ra­tion. For test­ing our com­mand, we will use the Tel­net pro­to­col be­cause it is easy to con­fig­ure and use, so we just need to copy the cor­re­spond­ing sec­tion in vertx-​http-client.js:

var ShellService = require("vertx-shell-js/shell_service");
var service = ShellService.create(vertx, {
  "telnetOptions" : {
    "host" : "localhost",
    "port" : 4000

We can run it:

Juliens-MacBook-Pro:java julien$ vertx run vertx-http-client.js
Succeeded in deploying verticle

And con­nect to the shell:

Juliens-MacBook-Pro:~ julien$ telnet localhost 4000
Trying ::1...
telnet: connect to address ::1: Connection refused
Connected to localhost.
Escape character is '^]'.
__      __ ______  _____  _______  __   __
\ \    / /|  ____||  _  \|__   __| \ \ / /
 \ \  / / | |____ | :_) |   | |     \   /
  \ \/ /  |  ____||   __/   | |      > /
   \  /   | |____ | |\ \    | |     / //\
    \/    |______||_| \_\   |_| o  /_/ \_\


You can now al­ready use the shell, the help com­mand lists the avail­able com­mands.

Creating a command

For the sake of sim­plic­ity we will write a sin­gle script that starts the Shell ser­vice and de­ploys our com­mand. In the real world you would prob­a­bly have the com­mand in one file and the de­ploy­ment in an­other.

The doc­u­men­ta­tion ex­plains how to add a new com­mand to Vert.x shell, we can just copy this sec­tion and ap­pend it to the vertx-​http-client.js script:

var CommandBuilder = require("vertx-shell-js/command_builder");
var CommandRegistry = require("vertx-shell-js/command_registry");

var builder = CommandBuilder.command("http-client");
builder.processHandler(function (process) {

  // Write a message to the console
  process.write("Implement the client\n");

  // End the process

// Register the command
var registry = CommandRegistry.getShared(vertx);

Now you can use the com­mand just to see it in ac­tion:

% http-client
Implement the client

Checking arguments

The http-​client re­quires an url ar­gu­ment, an ar­gu­ment check is per­formed at the be­gin­ning of the process han­dler:

// Check the url argument
if (process.args().length < 1) {
  process.write("Missing URL\n").end();
var url = process.args()[0];

Implementing the command

The final step of this tu­to­r­ial is the ac­tual im­ple­men­ta­tion of the client logic based on Vert.x Http­Client:

// Create the client request
var request = client.getAbs(url, function(response) {

  // Print the response in the shell console
  response.handler(function(buffer) {

  // End the command when the response ends
  response.endHandler(function() {

// Set a request handler to end the command with error
request.exceptionHandler(function(err) {
  process.write("Error: " + err.getMessage());

// End the http request

And we can test the com­mand in the shell:

% http-client
<!DOCTYPE html><html lang=en><head><title>Vert.x</title>...


We have seen how easy it is to ex­tend Vert.x with a shell and cre­ate an http-​client cus­tom com­mand, you can get the full source code here.

Our com­mand is very sim­ple, it only im­ple­ments the very min­i­mum, in fu­ture posts we will im­prove the com­mand with sup­port with more HTTP meth­ods, SSL sup­port or header sup­port with the the Vert.x CLI API.

Next post

Vert.x 3.2.1 is released!

We are pleased to announce the release of Vert.x 3.2.1!

Read more
Previous post

Using Hamcrest Matchers with Vert.x Unit

Vert.x Unit is a very elegant library to test asynchronous applications developed with vert.x. However because of this asynchronous aspect, reporting test failures is not natural for JUnit users.

Read more
Related posts

Unit and Integration Tests

Let’s refresh our mind about what we developed so far in the introduction to vert.x series. We forgot an important task. We didn’t test the API.

Read more

Building services and APIs with AMQP 1.0

Microservices and APIs are everywhere. Everyone talks about them, presentation slides are full of them ... some people are actually even building them.

Read more

Combine vert.x and mongo to build a giant

This blog post is part of the introduction to Vert.x series. We are now going to replace this JDBC client by the vertx-mongo-client, and thus connect to a Mongo database.

Read more