Nuxeo Shell

Nuxeo Shell works on top of Nuxeo Content Automation Client and is using the REST API provided by the Automation framework. Because it is using HTTP to communicate with the server the Shell can be used against any Nuxeo distribution which includes the automation framework.

This also means, most of the Shell commands are implemented as remote Automation operations.

 

Overview

Nuxeo Shell comes with a lot of features to improve your experience using the command line. Also, it provides high pluggability so you can extend it and add new commands in a simple way.

Here is a list of the most important features.

Interactive Execution

The Nuxeo Shell uses jline library for interactive mode. When you launch the Shell you will automatically enter the interactive mode. This mode provides a prompt and auto completion so you can easily browse a Nuxeo repository and execute commands.

Batch Execution

You can also launch the Shell in batch mode. In this mode you can specify a list of commands to be executed and then to return the control back to the terminal.

There are 3 batch modes available:

1. Run commands from a file
2. Run commands from standard input.
3. Run commands specified on the command line - this is a convenient way to run a short list of commands.

See the Shell Batch Mode page for more details.

Namespaces

Namespaces are commands registry that you can register in the Shell. A command registry is useful to bring inside the Shell a new set of commands for a specific context without having name clash problems with already existing commands.

To switch to a different namespace use the use command.

So for example, you may want to have ls command that is listing the content of a Nuxeo Folder when connected to a remote server but still use the ls command when switching to the local context to be able to list the content of a directory on the local file system.

Also, namespaces are hierarchical so a namespace my extend another one to adds more commands. Available namespaces are setup by the features installed in the Shell. By default, Nuxeo Shell provides the following default namespaces:

1. global - the global namespace. This provides global commands like help, 'use', 'cmds' etc.
2. local - provides file system commands like: ls, cd, cat, etc. Extends the global namespace.
3. remote - provides remote commands against a Nuxeo server. Extends the global namespace. Available only after connecting to a remote server.
4. automation - expose remote automation operations as commands. Available only after connecting to a remote server.

Auto Completion

Auto completion support is provided by jline. The Shell is leveraging this so that you can auto complete:

1. command names.
2. parameter names.
3. parameter values (when the command provide completion).

There are several type of objects that supports completion (like, file, document, etc.) but you can add more by implementing new completors.

Scripting

Nuxeo Shell is providing scripting capabilities through Groovy or Mvel. You can execute thus your Groovy scripts on the server JVM. There are two ways of executing scripts:

1. Either invoke a script file from your file system using the script command.
2. Or write a command that execute a script (instead of executing a remote automation operation).

Documentation Generation

Command documentation pages are automatically generated by the Shell by introspecting the command annotations.

Also, if you want to add more details like in-depth explanation of the command, examples etc. then you can write this in a text file and the Shell will automatically append it to the generated documentation.

When writing custom documentation you can use tags like {header}, {bold}, {red}, {green} etc. to control the formatting on the terminal.

Automation Chain Execution

You can execute any automation chain exposed by the server by using the run or runonfile commands. This is useful since you can create your administration commands in Nuxeo Studio by creating Automation Chains.

Direct Operation Execution

The automation mode provides Shell commands for any operation available on the server. These commands are automatically generated from operation descriptors.

This mode should be used only to debug operations or to execute some operations not exposed through specialized commands by the Shell.

Exception Handling

In the interactive mode unchecked exceptions are printed in red on the screen. Checked exceptions are not printed - only the exception message is printed out. If you need to see the stack trace of the last exception type trace.

Extensibility

A Shell feature is providing Shell configuration such as namespaces, commands, completors, etc. To extend the capabilities of the Shell you can register a new feature which will install the new capabilities into the Shell at boot time.

The Shell can be extended either by modifying the Nuxeo Shell JAR or by adding on the classpath JARs containing additional Nuxeo Shell features.

See Extending the Shell section for more details.

Usage

Shell Applet

The Shell is available as an applet in the Admin Center, in the "Monitoring" tab.

 

Launching the Shell from Command Line

You can launch the Shell either by running the command:

java -jar nuxeo-shell.jar

or by running:

java -cp nuxeo-shell.jar org.nuxeo.shell.Main

The difference is that the first command will launch the Shell in a Swing based terminal (i.e. a desktop application) while the second one will launch the Shell inside your current terminal. On some Operating Systems like Windows double clicking the nuxeo-shell.jar will launch the Shell in a Swing based terminal.

When launching the Shell the local namespace is automatically activated.

When connecting to a remote server the Shell will automatically switch to remote namespace. When disconnecting it will go back to the local namespace.

To switch between namespaces just use the use command. For example if you are in the remote namespace you can switch to the local one by executing the command:

use local

Getting the Shell Version

You can launch the Shell using

java -jar nuxeo-shell.jar --version

to get information about the Shell version and the minimal server version required by the Shell to correctly run against a remote server.

You can also have this information by using the version command.

Connecting to a Server

To connect to a remote Nuxeo Server you must specify the Automation Service URL.

This URL is in the form:

http://NUXEO_SERVER/nuxeo/site/automation

For example, in the case of a local server your URL will be:

http://localhost:8080/nuxeo/site/automation

To connect to a server you should use the global connect command. This command require 3 parameters:

1. the URL of the remote automation service.
2. the username to login
3. the password to login

You can either pass these arguments to the connect command itself or through the command line when starting the Shell.

You can use -u for the username, -p for the password and the URL should be given as argument.

If password is not specified you will be prompted for a password when in interactive mode.

Example

Here is an example of a short session:

After launching the Shell you are in local mode. So you can use the provided file system commands like:

• ls - to list the content of the current directory.
• cd, pushd, popd - to change the current directory.
• cat, mv, cp, etc. for other file based operations.

To connect to a remote server type:

connect http://localhost:8080/nuxeo/site/automation -u Administrator

After the connection is done you are automatically switched in remote namespace.

So doing now a ls will list the content of the current document. (which for now the root document).

To switch back in local namespace type:

use local

To show the current namespace name type:

use