{section}
{column}

h1. Introduction

Petals Registry CLI is a command line client to administrate a set of Petals Registry Overlay nodes.
Petals Registry CLI has 4 interaction modes:
* *Interactive Mode:* [in this mode|#Interactive console], the user types in commands directly in the shell.
* *Scripting Mode:* [in this mode|#Execution of a Petals script file], Petals Registry CLI executes a script file that contains Petals Registry CLI commands.
* *Executable Mode:* [in this mode|#Execution of a Petals Registry CLI command directly on the command line], Petals Registry CLI is launched with a command as an argument.
* *Redirection Mode:* [in this mode|#Execution of an inlined Petals script], Petals Registry CLI takes the commands to execute from the standard input.

To work, Petals Registry CLI needs to establish a connection with a Petals Registry node.
The connection is a JMX connection (see the credentials defined in the _cluster.xml_ file of Petals Registry Overlay).

{warning}
Petals Registry CLI *1.0.0+* works with Petals Registry Overlay *1.0.0* and higher.
Petals Registry CLI *1.1.0+* works with Petals Registry Overlay *1.0.1* and higher.
Petals Registry CLI *1.1.1+* works with Petals Registry Overlay *1.0.2* and higher.
{warning}

h1. Usage of Petals Registry CLI

{code}
usage: Petals Registry Command Line Interface

[-d] [-y] usage: [-a <alias>] [-g <group-name>] [-h <host>] [-n <port>] [-p
<group-password>] [-y]
[-H | -V | [--file] <filename> | -c -- <command> | -C]
-a,--alias <alias> Connection alias in the preference file.
-c,--command Execute a command given on the command line after
'--'.
-C,--console Enable the mode 'console'.
-d,--debug Print stack trace and debugging informations
--file <filename> Enable the script file execution. If filename is '-',
commands are read from the stdin.
-g,--group <group-name> The group name of the Petals Registry cluster to
connect.
-H,--help Print this help message and exit.
-h,--host <host> The host of a member of the Petals Registry cluster to
connect.
-n,--port <port> The port of the Petals Registry cluster to connect.
-p,--password <group-password> The password of the Petals Registry cluster to
connect.
-V,--version Print the version number and exit.
-y A flag to skip confirmation.

Which evolution would you like on Petals? Share it! http://www.petalslink.com/feedback
{code}

To get available commands, use the command 'help' on command-line: petals-cli.sh -c -- help
{code}
Available commands:
connect Connect to a Petals Registry cluster.
delete-topology
Delete the given topology.
disconnect
Disconnect from a Petals Registry cluster.
exit Exit this shell.
help Display this help message or help for a specific command.
list-topologies
List the topologies registered.
load Load properties from files.
print Print a message.
pwd Print the working directory.
set Assign a value to the system property named key.
system Execute system command.

For help on a specific command type:
help <command>
{code}

To get help on a command, use the command 'help' on command-line: petals-registry-cli.sh -c -- help <command>

{tip}Options of Petals Registry CLI are [POSIX.1-2008|http://pubs.opengroup.org/onlinepubs/9699919799/] or [IEEE Std 1003.1|http://pubs.opengroup.org/onlinepubs/9699919799/] compliant.{tip}

{column}
{column:width=40%}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

h1. Use Cases

{gliffy:name=Petals_Registry_CLI_Use_Cases|align=center|size=M|version=3}

h1. Petals Registry CLI: the Basis

h2. Installing Petals Registry CLI

The installation of Petals Registry CLI depends on your operating system. The following table resumes which archives is needed according to your operating system. Petals Registry CLI archives are available on the Petals's web-site: [http://download.petalslink.com/petals-esb.html].
|| Operating System || OS Version || Petals archive to use || Installation procedure ||
| Debian-based Linux | all | Debian packages | [Installing Petals Registry CLI using the Debian packages]|
| Linux | all | ZIP archive | [Installing Petals Registry CLI using the ZIP archive] |
| Microsoft Windows | all | ZIP archive | [Installing Petals Registry CLI using the ZIP archive] |
| Mac OS | all | ZIP archive | [Installing Petals Registry CLI using the ZIP archive] |

+Note:+ The ZIP archive can be used on Debian-based systems. In this case, Petals Registry CLI should be installed as a user software without integration with the operating system.

h2. Petals Registry CLI capabilities about script and shell usages

h3. Interactive console

Launching Petals Registry CLI with the following command line starts an interactive console with a prompt where the user can enter commands.
{code}
> ./petals-reg-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli>
{code}

h3. Execution of a Petals Registry CLI command directly on the command line

Launching Petals Registry CLI with the following command line executes the command specified on the command line.
{code}
> ./petals-registry-cli.sh -c -- <command> <command-args>
{code}

h3. Execution of a Petals script file

Launching Petals Registry CLI with the following command line executes the commands from the specified Petals script.
{code}
> ./petals-registry-cli.sh <filename>
> ./petals-registry-cli.sh --file <filename>
{code}

{info}A Petals script is text file containing commands supported by Petals Registry CLI, and comments. Comments start by '{{#}}', optionally preceded by space(s).{info}

h3. Execution of an inlined Petals script

Launching Petals Registry CLI with the following command line executes commands provided through the standard input ("stdin").

{code}
> cat <filename> | ./petals-registry-cli.sh -
> cat <filename> | ./petals-registry-cli.sh --file -
> ./petals-registry-cli.sh - << EOF
<command1> <command1-args>
<command2> <command2-args>
EOF
> ./petals-registry-cli.sh --file - << EOF
<command1> <command1-args>
<command2> <command2-args>
EOF
{code}

h2. Getting help

h3. Getting help on command line options and arguments

The help on command line options and arguments is available through the '_\-H_' option. A text containing options, arguments and available commands is displayed according to the usage defined above.
{code}
> ./petals-registry-cli.sh -H
{code}

h3. Getting help on commands from the command line

The help on a command is available by using the command '_help_'. A usage and a description of the command is displayed:
{code}
> ./petals-registry-cli.sh -c -- help <command>

usage: <command> <command-arguments>

<command description>

>
{code}
where:
* {{<command>}} is the command for which we want to get help.
* {{<command-arguments>}} is the list of arguments for the command.
* {{<command-description}} is a description of the command.

h3. Getting help on available commands and on a command in interactive mode

The list of available commands is available by using the command '_help_' without argument.
Help about a command is available by using the '_help_' command. Command's usage and description are then displayed.
{code}> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> help
Available commands:
connect Connect to a Petals Registry cluster.
delete-topology
Delete the given topology.
disconnect
Disconnect from a Petals Registry cluster.
exit Exit this shell.
help Display this help message or help for a specific command.
...

For help on a specific command type:
help <command>

petals-registry-cli> help <command>

usage: <command> <command-arguments>

<command description>

petals-registry-cli>
{code}
where:
* {{<command>}} is the command for which we want to get help.
* {{<command-arguments>}} is the list of arguments for the command.
* {{<command-description}} is a description of the command.

h2. Getting the version of Petals Registry CLI

To get the version of Petals Registry CLI, the version of the JVM running Petals Registry CLI, and its operating system, use the '_\-V_' option:
{code}
> ./petals-registry-cli.sh -V
Petals Registry Command Line Interface 1.1.0
OpenJDK Runtime Environment 1.7.0_91-b02 Oracle Corporation
Linux 4.2.0-22-generic amd64
{code}

h2. Working with variables

Petals Registry CLI supports variables as properties or environment variables. A variable is a placeholder with a name: {{${variable-name\}}}, that is replaced by its value when evaluating the command in which it is used. By default, a variable is a property. An environment variable is identified by a name prefixed with "env:":
{code}
connect -h ${host.name} -n ${host.port} -u ${env:USER} -p ${host.password}
{code}

h3. Listing available variables

The command '_set_' without argument lists all available variables, properties and environment variables:
{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> set
...
java.runtime.name=OpenJDK Runtime Environment
java.runtime.version=1.7.0_79-b14
java.specification.name=Java Platform API Specification
java.specification.vendor=Oracle Corporation
java.specification.version=1.7
...
env:PATH=usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/cdeneux/maven/bin
...
{code}

h3. Setting a variable as property

A property can be set using the command '_set_':
{code}
set [ property-name = property-value ]
set [ property-name =: property-value ]
set [ property-name : property-value ]

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> set my-property-name=value
{code}

h2. Return codes of Petals Registry CLI

h3. Return code on error parsing mode options

If Petals Registry CLI is not able to determine the mode (interactive, scripting, executable or redirection) to use from arguments, the return code will be 1.

h3. Return code of Petals Registry CLI launched in interactive mode

Petals Registry CLI launched in interactive mode will exist always with the return code 0, even if error occurs executing a command.
If an error occurs during a command execution or parsing:
* The error message is displayed.
* Petals Registry CLI is not interrupted, the user can enter other commands.

h3. Return codes of Petals Registry CLI launched in command line mode

h4. Return code on parsing error of the command arguments

When there is an error about options and arguments of the command, the return code of Petals Registry CLI is 1.

h4. Return code on command execution

When there is an error about the command execution, the command is interrupted and the return code of Petals Registry CLI is 2.

h4. Return code on connection error

When there is an error about the connection establishment, the command is not executed the return code of Petals Registry CLI is 3. If the error is due to an unresolvable hostname, the return code is 1 (ie. error on arguments).

h4. Return code on successful command execution

When there is no error about options, arguments and execution of a the command, the return code of Petals Registry CLI is the return code of the command

h3. Return code of commands

All commands return the return code 0 when the execution succeeds, and 1 when the execution fails. Except the command '{{system}}' that returns the return code of the system command invoked.

h3. Return codes of Petals Registry CLI launched in scripting modes

h4. Return code on error reading script

When there is an error reading the command flow, Petals Registry CLI script is interrupted and the return code of Petals Registry CLI is 1.

h4. Return code on parsing error of the command arguments

When using the script mode or inlined mode, parsing errors (invalid options and/or arguments) result in an interruption of Petals Registry CLI.
The return code 1 then pushed back.

h4. Return code on command execution

When there is an error about a command execution, the command is interrupted, Petals Registry CLI script is interrupted and the return code of Petals Registry CLI is 2.

h4. Return code on connection error

When there is an error about the connection establishment, the command is not executed and the return code of Petals Registry CLI is 3. If the error is due to an unresolvable hostname, the return code is 1 (ie. error on arguments).

h4. Return code on successful command execution

When there is no error about options, arguments and execution of commands, the return code of Petals Registry CLI is the return code of the last command, except if a dedicated value is used through the command {{exit}}.

h4. Error management of a command read from stdin or a file

If an error occurs during the execution of a flow of commands:
* The command that has thrown the error is interrupted.
* The return code of the command can be checked using the commands _isParsingErrorReturned_, _isExecutionErrorReturned_, _isNoErrorReturned_, the ternary conditional operator, and the _lastErrorCode_ attribute.
{code}
> ./petals-registry-cli.sh - << EOF
list-topologies
isNoErrorReturned ? listartefacts : exit lastErrorCode
EOF
{code}

\\
Note:
* The return values of command {{isParsingErrorReturned}}, {{isExecutionErrorReturned}} and {{isNoErrorReturned}} are reset when invoking another command. Only the error of the last command execution can be checked.
* The attribute {{lastErrorCode}} is an argument of the command {{exit}} to return the return code of the last executed command.

h2. Exit from the Console mode

To exit the console mode, use the '_exit_' command.
If a number is set as an argument, it is used as return code. Otherwise, the 0 is returned.
{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> exit
> echo $?
0
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> exit 1
> echo $?
1
{code}

{note}If an asynchronous command is running, the command 'exit' will wait the end of these pending commands to really exit. If you have infinite asynchronous command as defect subscription, you can force to exit using Ctrl+C or kill the process.{note}

h2. Petals Registry CLI Preferences

It is possible to define preferences in Petals Registry CLI. The preferences are defined in a properties file, as key/value pairs. Two levels of preference files are defined:
* a user level, by the file {{$HOME/.petals-cli/petals-registry-cli.default}}
* and a system level. The location of this file is defined according to the operating system:
|| OS/Distribution || System level file ||
| Linux/Debian-based distribution | {{/etc/petals-registry-cli/petals-registry-cli.default}} |
| Windows | {{%PETALS_REGISTRY_CLI_HOME%\conf\petals-registry-cli.default}} |

If the user preference file exists, it is used. Otherwise the system preference file is used.

{tip}
If Petals Registry CLI is installed through the ZIP archive, and no user level file exists, it is possible to define another preference file through the environment variable _$PETALS_REG_CLI_PREFS_.
{tip}

{tip}
If Petals Registry CLI is installed through the Debian archive, the default preference file is protected by system ACL and can be read only by users that are member of its group. So don't forget to add you users to the security group, or you can protect this file with your own group.
{tip}

The preferences files contain a set of keys in several sections:
* section 'Global preferences':
** *alias.default*: the default alias to use (required).
** *user.lang*: the language to use in Petals Registry CLI.
*** This property is optional. If not set, OS settings are used. If the OS language setting is not supported, then English is used.
*** If the value is specified and not supported, then English is picked up.
*** French and English are the two languages that must be supported. Others are optional (but contributions are welcome).
* section defining aliases. An alias identifies all the properties of a connection. An alias is defined as following:
** *<alias>.host*: the host of a member of the Petals Registry Cluster (required).
** *<alias>.port*: the port of the member of the Petals Registry Cluster (required).
** *<alias>.group*: the group name of the registry instance (optional).
** *<alias>.password*: the password to join the registry instance (optional).
When optional keys are not defined, Petals Registry CLI will ask for their values manually (or you will have to use the right options with the commands).
If the file does not exist, or that _$PETALS_REG_CLI_PREFS_ points to an invalid location, Petals Registry CLI will use default settings when possible. Otherwise, it will display an error message.

\\
For a cluster member, the *group* and *password* must both be set or both be absent.
An error message is displayed if only one of them is specified.

\\
The server alias must be unique in the properties file.
If a server alias is used twice, an error message will be displayed.

\\
Initial content of the file:
{code}
# The default server / connection
alias.default = default

# The connection properties of the 1st cluster member
default.host=localhost
default.port=7900
default.group=default-sample
default.password=s3cr3t

{code}

h2. Petals Registry CLI extensions

No Petals Registry CLI extensions is available now, [contributions are welcomed|#add_your_own_command].

h1. Connection to a Petals Registry member

h2. Connection options from the command line

All the required parameters for a connection can be configured on the command line as options or through the command {{connect}}:
{code}
> ./petals-registry-cli.sh -h <host> -n <port> -g <group> -p <password> -c -- <command>
> ./petals-registry-cli.sh -C
petals-registry-cli> connect -h <host1> -n <port1> -g <group1> -p <password1>
petals-registry-cli@<host1>:<port1>>
{code}

An alias can also be used.
{code}
> ./petals-registry-cli.sh -a <alias> -c -- <command>
> ./petals-registry-cli.sh -C
petals-registry-cli> connect -a <alias1>
petals-registry-cli@<host1>:<port1>>
{code}

{tip}The arguments {{-h}}, {{-p}}, {{-g}}, {{-p}} and {{-a}} of the command line are significant only for the command line mode (ie. {{-c}}){tip}

h2. Default connection

In console mode, the connection is established, by the command 'connect', with the values given in the preferences file. The connection parameters are identified through the default alias defined by the property {{alias.default}} of the preferences file.
{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect
petals-registry-cli> Would you like to connect to <default-group>:*****@<default-host>:<default-port>? (y/n)
y
petals-registry-cli@<default-host>:<default-port>>
{code}

The confirmation can be skipped by adding the '_yes_' argument to the command.
{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect -y
petals-registry-cli@<default-host>:<default-port>>
{code}

In command line mode, no default connection is available. A connection is *automatically* established with the connection parameters explicitly set on the command line.

{code}
> ./petals-registry-cli.sh -h localhost -n 7700 -g default-sample -p petals -c -- list-topologies
> ./petals-registry-cli.sh -a default -c -- list-topologies
{code}

In script mode, the connection is established, by the command 'connect', with the values given in the preferences file. The connection parameters are identified through the default alias defined by the property {{alias.default}} of the preferences file.
{code}
> ./petals-registry-cli.sh - << EOF
connect
EOF
{code}

If the preferences file does not exist and that _connect_ was invoked without an argument, the command returns the error code 2.

h2. Interacting with several Petals nodes without exiting Petals Registry CLI

In interactive mode or script mode, we should be able to close a connection and open another one without leaving Petals Registry CLI. This is achieved with the '_connect_' and '_disconnect_' commands. If no argument is set on the '_connect_' command, default values are used. These default values are specified in the preferences file. If a connection already exists, the '_connect_' command will realize a disconnection before to establish the new connection.

{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect -h <host1> -n <port1> -g <group1> -p <password1>
Connected on <host1>:<port1> with '<group1>'
petals-registry-cli@<host1>:<port1>> disconnect
petals-registry-cli> connect -a <alias>
Connected on <host1>:<port1> with '<group1>'
petals-registry-cli@<host1>:<port1>> disconnect
petals-registry-cli> connect -h <host2> -n <port2> -u <group2> -p <password2>
Connected on <host2>:<port2> with '<group2>'
petals-registry-cli@<host2>:<port2>> connect
petals-registry-cli@<host2>:<port2>> Would you like to connect to <default-user>:*****@<default-host>:<default-port>? (y/n)
y
petals-registry-cli@<default-host>:<default-port>>
{code}

h2. Security

For security reasons, a Petals Registry CLI user may decide that there should be no default connection.
In that case, he may decide to delete the preference file, so that any user will have to type in the right information.
If the preference (properties file) does not exist, Petals Registry CLI displays an error message.

{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect
No default connection is available. Use 'help connect' for more information.
{code}

\\
Another possibility is that the user allows to record a default host and port but not the credentials.
In that case, Petals Registry CLI will ask the user to type in the credentials.

{code}
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect
petals-registry-cli> Would you like to connect to <default-host>:<-default-port>? (y/n)
y
petals-registry-cli> Group name: wrong-groupname
petals-registry-cli> Password: right-pwd
Invalid credentials.
petals-registry-cli> Retry? (y/n)
y

petals-registry-cli> Group name: right-groupname
petals-registry-cli> Password: wrong-pwd
Invalid credentials.
petals-registry-cli> Retry? (y/n)
y

petals-registry-cli> Group name: right-groupname
petals-registry-cli> Password: right-pwd
petals-registry-cli@<default-host>:<-default-port>>
{code}

h2. Error Messages

{tip}Error messages should be written in active form.
Negative forms should be avoided.{tip}

\\
The preferences file does not exist.
The connect command results in the following error message.

{quote}No default connection is available. Use 'help connect' for more information.{quote}

\\
The preferences file is invalid (missing property, or duplicate alias...).
The connect command results in the following error message.

{quote}The preferences file contains <N> error(s).
- Error 1
- Error2{quote}

\\
Duplicate Alias.
{quote}The alias '<alias>' can only be used once.{quote}

\\
Missing property.
{quote}The property '<property>' is missing.{quote}

\\
Only *group* was specified for a server.
{quote}The credentials for '<alias>' are invalid: add the password or remove the group.{quote}

\\
Only *password* was specified for a server.
{quote}The credentials for '<alias>' are invalid: add the group or remove the password.{quote}

h1. Administration Commands

h2. Working with topologies

h3. Getting the topology

When connected to a Petals Registry member container, it is possible to get information about the Petals ESB topologies hosted by this registry.

{code}
petals-registry-cli@host:port> list-topologies
PEtALS

{code}

This command returns the list of topologies hosted.

h4. Filtering

The list of the topologies can be limited using the filter '{{-p <topology-pattern>}}', where _{{topology-pattern}}_ is a regexp identifying the topologies to list:
{code}
petals-registry-cli@host:port> topology-list -p P.*
PEtALS
{code}

h3. Removing a topology

When connected to a Petals Registry member container, a remaining topology can be removed from the Petals Regsitry using the command _{{delete-topology}}_:
{code}
petals-registry-cli@host:port> delete-topology -t <topology-name>

{code}
where _{{topology-name}}_ is the name of the topology to delete.

h2. System Commands

Petals Registry CLI can directly execute system commands.
To achieve it, the system command is an argument of the '_system_' command.

{code}
petals-registry-cli> system <system-command>
{code}

As an example,

{code}
petals-registry-cli> system pwd
{code}

displays the directory in which Petals Registry CLI runs.
The return code of the wrapping command is the return code of the system command.

{info}
A system command having arguments can also be enclosed with quotes:
{code}
petals-registry-cli> system "echo My linux shell: ${env:SHELL}"
My linux shell: /bin/bash
{code}
{info}

{tip}
Caution to correctly escape the symbol '{{$}}' when using a system command with variables on command line:
{code}
$ petals-registry-cli -c -- system echo My linux shell: \${env:SHELL} with the temporary folder: \${java.io.tmpdir}
My linux shell: /bin/bash with the temporary folder: /tmp
$ petals-registry-cli -c -- system "echo My linux shell: \${env:SHELL} with the temporary folder: \${java.io.tmpdir}"
My linux shell: /bin/bash with the temporary folder: /tmp
{code}
{tip}

h1. Advanced usage

h2. Logging in Petals Registry CLI

Petals Registry CLI is provided with a default Java Logging configuration. This configuration displays logging trace as following:
{code}
<LEVEL>: <message>
{code}
where <LEVEL> is the international label of the logging trace level, except for the level '{{SEVERE}}' which is always '{{ERROR}}'. By default, only levels '{{SEVERE}}' and '{{WARNING}}' are printed.

The default configuration can be overridden using the system property '{{java.util.logging.config.file}}' to set into the launching script '{{$PETALS_REG_CLI_HOME/bin/petals-registry-cli.sh}}' or '{{%PETALS_REG_CLI_HOME%\bin\petals-registry-cli.bat}}'. An sample configuration is available in file '{{$PETALS_CLI_HOME/conf/petals-registry-cli-logging-sample.properties}}'

{anchor:add_your_own_command}

h2. To add your custom command

Petals Registry CLI is provided with an API to add your own command.

h3. Writing your command

To create a new custom command, just create a new Java class that *IMPLEMENTS* the interface {{org.ow2.petals.cli.api.command.Command}}.
To be auto-discovered, your command *MUST* be declared in a resource named '{{META-INF/service/org.ow2.petals.cli.api.command.Command}}' (put the class name with the package part in this file).

If the new command needs third party products in addition of the ones already provided by Petals Registry CLI, they *MUST* be installed with your command.
{warning}No classloader isolation is available between commands, pay attention to versions of third-party products. They MUST match the version of those provided with Petals Registry CLI or those custom commands.{warning}

h3. Custom command installation

To install your command just put all needed JAR files in the directory {{$PETALS_REG_CLI_HOME/extensions}}.

h1. Known Problems

h2. Petals Registry CLI seems to be frozen on command 'exit'

You entered the command exit in the interactive mode, and the Petals Registry CLI seems to be frozen: no prompt.
You probably have launched asynchronous commands as defect subscriptions, use Ctrl-C to force to exit the Petals Registry CLI or kill its process.