Search the documentation
 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 6.0 Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.3

The OpenCms shell is an executable that allows one to interact with OpenCms from the command line. You can also pass a script to the shell that should be executed. Hence, it is the tool to automate tasks and, for example, execute them within the scope of a larger normal shell script.

What's the benefit of an OpenCms shell?

The OpenCms shell is perfect for automating tasks. In particular, tasks that include not only OpenCms specific parts, but also "normal" shell commands. You can call the OpenCms shell from a shell script and paste it an OpenCms script that it should execute.

Particular use cases are

  • Automatically install extra modules when deploying OpenCms
  • Automatically export database data or modules, e.g., for moving the exported data to another server for backup.

The OpenCms shell also supports import and export in clusters.

Calling the OpenCms shell

The OpenCms shell is shipped with the standard OpenCms installation. It's the executable class org.opencms.main.CmsShell. To start the shell the scripts

  • cmsshell.bat (for Windows)
  • cmsshell.sh (for Linux)

that are placed in the folder {webapp home}/WEB-INF should be used to start the shell. They set the correct extra parameters for excuting the Shell and start it.

The OpenCms shell takes several arguments on startup that can also be given to appropriate start scripts.

Arguments for calling the shell
-base

Set the absolute path to the OpenCms installation's base directory, i.e., {absolute path to the webapp home}/WEB-INF. If not provided, the path is read from the system property user.dir. The start scripts set this argument automatically.

-script

Provide the path to a OpenCms shell script file. Such a file lists a series of OpenCms shell commands. The commands are all executed when handing the script to the shell on startup.

The last command in your OpenCms shell script should be quit or exit, because mixing batch mode and interactive mode is not supported.
-servletMapping

The servlet mapping defined in the web.xml of the OpenCms installation. If not given /opencms/* is used as the default.

-defaultWebApp

The webapp name of the default webapp as configured for your servlet container. The default value is ROOT, as it is in a standard Tomcat installation.

-additional

Add additional shell commands by providing the fully qualified name of a class that implements I_CmsShellCommands to make all commands defined in that class available in the shell.

Working with the OpenCms shell

We describe how to work with the OpenCms shell in interactive mode, i.e., without passing a script to the shell. But most information is also useful for writing scripts, because in batch mode, the shell starts exactly as in interactive mode - it's just that the commands you would type in interactive mode are all read from the given script.

When the shell starts it starts a new OpenCms instance and displays some information on the startup process plus help information. When startup is finished, you'll see a prompt where you can type commands.

Fig. [shell_startup]: The OpenCms shell on startup

The most important information is the help option on commands. You can get the signature of all available methods that make up commands, grouped by the classes that provide the methods, using help *. You can also search for signatures of methods whose name contains a special substring by typing help {string}. This search is not case-sensitive.

Signatures are shown as methodName(arg1,arg2,..,argn). To use the method as command type methodName arg1 arg2 ... argn.

Let's see a very simple use case of the help function. You want to log in to OpenCms, but don't know exactly how. Thus, you search for login commands via help login. The shell will tell you:

Guest@Online:|/>help login  

Available methods in org.opencms.main.CmsShellCommands:
* login(String, String)

Available methods in org.opencms.file.CmsObject:
* loginUser(String, String)
* loginUser(String, String, String)

You'll see three available methods that can be used as commands. To get further information on the methods, look up the JavaDoc of the classes that implement the methods. We assume we know already that the login method takes a username and a password. Thus we log in as follows:

Guest@Online:|/>login Admin admin
You are now logged in as user "Admin".
Admin@Online:|/>

Which commands are available?

The available commands are public methods from various classes. But not all public methods make up a command. The methods must have sufficiently simple arguments. That means, all arguments must have a "simple" type.

The types that are supported for command arguments are the arguments parsable via org.opencms.util.CmsDataTypeUtil.isParseable.

By default commands are exposed for methods of the following classes:

You can look up descriptions of the methods available as commands in the JavaDoc.

Using the argument -additional when calling the OpenCms shell, you can add an extra class for exposing methods. The class must implement I_CmsShellCommands.

Typing help * in the shell, you can always get an overview of the available commands.

How does the OpenCms shell work?

When you call the OpenCms shell, a new instance of OpenCms is started. You do not need to have OpenCms already running in your Tomcat (or other servlet container). You do not even need to start the servlet container at all.

You should be aware that the shell starts a new OpenCms instance. That may interfere with an already running instance started by Tomcat. So we strongly recommend not using the shell while OpenCms is already running.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.