Tech and Media Labs
This site uses cookies to improve the user experience.

Vert.x Command Line

Jakob Jenkov
Last update: 2015-08-29

It is possible to run Vert.x from the command line using the vertx command. The vertx command makes it possible to start up Vert.x and deploy a verticle to it, directly from the command line. That means that you don't have to create a Vertx instance and deploy verticles to it programmatically.

The Vert.x command line is pretty handy in some situations. For instance, the Vert.x command line makes it easy to deploy verticles implemented in different programming languages in the same Vertx instance. This makes Vert.x a true polyglot platform.

Adding the Vert.x bin Directory to the Path Environment Variable

Before the Vert.x command line works you must have installed Vert.x (download and unzip to the desired directory).

When Vert.x is installed, add the vertx-install-dir/bin to your Path environment variable. That is all that is needed. The vertx-install-dir part should be replaced with the actual directory into which you installed Vert.x.

Testing the Vert.x Command Line

Once you have added the vertx-install-dir/bin to the path environment variable, open a command prompt and run this command:

vertx -version

If Vert.x is correctly installed you should see an output similar to this:


This is the version of Vert.x that you have installed.

Deploying a Java Verticle

To deploy (run) a verticle on Vert.x via the Vert.x command line, you must use the vertx run command. After the vertx run part of the command you must write the fully qualified class name of the verticle to deploy. Here is a Vert.x command line Java verticle deployment example:

vertx run com.jenkov.vertx.MyVerticle

This command runs the Java verticle class named com.jenkov.vertx.MyVerticle .

To deploy a verticle class you must run the vertx run classname command from the root directory of the compiled classes for the verticle to deploy. Thus, the root directory of your classes becomes the classpath for deploying the verticle. Whatever directory you run the vertx run command from is automatically added to the classpath when looking for the verticle class.

You can also run a Java verticle class which is located inside a JAR file. Here is how the Vert.x command looks for that:

vertx run com.jenkov.vertx.MyVerticle -cp MyVerticle.jar

Longer Casspath

Sometimes you need a classpath which contains more than one directory or JAR file. In those situations you can provide a normal classpath string as the -cp argument value. Each entry (directory or JAR file) in the classpath string must be separated by either a semicolon (on Windows) or a colon (on Unix / Linux). Here is a longer classpath example:

vertx run com.jenkov.vertx.MyVerticle -cp MyVerticle.jar;SomeUtilLib.jar

This example contains two JAR files in the classpath separated by a semicolon.

Building the Classpath in a Script

If you have a very long classpath your command line may get very long, and thus be hard to read in a text editor. Instead you can build the classpath up as an environment variable, one entry per line, and use that environment variable in the command line. I will show you how to do that in both Windows and Linux.

First a Windows .cmd script:

set MY_CP=build\classes
set MY_CP=%MY_CP%;lib\util-1.jar
set MY_CP=%MY_CP%;lib\util-2.jar
set MY_CP=%MY_CP%;lib\util-3.jar

vertx run com.jenkov.vertx.MyVerticle -cp %MY_CP%

Save this script as e.g. run.cmd and you can execute it from a Windows command line. Notice how the script builds up an environment variable named MY_CP and then use that environment variable as argument value for the -cp switch.

Here is the Linux version of the same script:

export JAVA_HOME


/mystuff/vertx/vert.x-3.0.0/bin/vertx run com.jenkov.vertx.MyVerticle -cp $MY_CP

First of all, notice that the script creates a JAVA_HOME environment variable. Vert.x seems to need this environment variable set to run on Linux. Probably because Vert.x uses the Java SDK to run the Vert.x platform and possibly some of the other tools in the Java SDK. Make sure the JAVA_HOME point to the install directory of your Java SDK.

Second, the script builds a variable named MY_CP just like the Windows version did (though the code looks different). Notice the use of / as directory separator and the use of : as classpath entry separator.

Third, the script runs Vert.x, passing the MY_CP variable as argument value for the -cp switch. Notice how the command line contains the full path to where the vertx script is located (inside the Vert.x install directory). By referencing the vertx command using a full path to its location, you do not need to add the vertx command to your path environment variable (I have only tested this on Linux - not on Windows).

Deploying Verticles Written in Other Languages

As I mentioned in the Vert.x introduction - Vert.x is a polyglot platform. That means that you can deploy verticles written in other languages than Java. You can even deploy all these verticles into the same running instance of Vert.x .

Here is an example of deploying a verticle written in JavaScript:

vertx run my-verticle.js

As you can see, you just list the name of the verticle's JavaScript file and Vert.x will deploy it. It works the same for other languages like Ruby, Python etc. Vert.x will guess what language the file is written in based on the file extension.

If you want to you can tell Vert.x explicitly what language the file is implemented in. That might be useful if you deploy a class file that is written in Groovy or Scala (but which are compiled into Java classes). You tell Vert.x the language by prefixing the file name with the language, like this:

vertx run javascript:my-verticle.js

Notice the javascript: in front of the file name.

Jakob Jenkov

Copyright  Jenkov Aps
Close TOC