{section}
{column}
h1. Introduction

Petals CLI is a command line client to administrate a set of Petals nodes.
Petals 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 CLI executes a script file that contains Petals CLI commands.
* *Executable Mode:* [in this mode|#Execution of a Petals CLI command directly on the command line], Petals CLI is launched with a command as an argument.
* *Redirection Mode:* [in this mode|#Execution of an inlined Petals script], Petals CLI takes the commands to execute from the standard input.

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

Petals CLI works with Petals 4 and higher, but may also work with Petals 3 versions.
{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_CLI_Use_Cases|align=center|size=L|version=5}

h1. Usage of Petals CLI

{color:red}Needs to be updated{color}

{code}
usage: Petals JMX Command Line Interface

[-d] [-y] [-h <host>] [-n <port>] [-u <user>] [-p <password>] [-H | -V | [--file ] <filename> | -c <command> <command-args> | -C]

-c,--command <command> Execute a command given on the command line.
-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.
-H,--help Print this help message and exit.
-h,--host <host> remote petals ESB host name.
-n,--port <port> port number.
-p,--password <password> password.
-u,--user <user> username.
-V,--version Print the version number and exit.

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

Available commands:
- deploy: Deploy and start a JBI artifact in petals container.
- start: Start a JBI artifact or the container.
- stop: Stop a JBI artifact or the container.
- undeploy: Stop and uninstall or undeploy JBI artifacts.
- exit: Exit this shell.
- help: Display this help message or help for a specific command.
- list: List JBI artifacts name and current status.
- registry-sync: Force a registry synchronization
- registry-list: List the entries of the registry.
- version: Print version informations about petals container.
- show: Print informations about a JBI artifact.
- load: Load properties from files.
- print: Print a message.
- pwd: Print the working directory.
- set: Assign a value to the system property named key.

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

h1. Petals CLI: the Basis

h2. Petals CLI capabilities about script and shell usages

h3. Interactive console

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

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli>

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

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

h3. Execution of a Petals script file

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

{info}A Petals script is text file containing commands supported by Petals CLI.{info}

h3. Execution of an inlined Petals script

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

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

h2. Getting help

{code}

usage: <command> <command-arguments>

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.

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> help

Available commands:
deploy Deploy and start a JBI artifact in petals container.
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-cli> help <command>

usage: <command> <command-arguments>

* {{<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.

Petals JMX Command Line Interface 1.1.0-SNAPSHOT
Java(TM) SE Runtime Environment 1.6.0_26-b03
Linux 3.0.0-16-generic-pae

h3. Return code on successful result

When there is no error about options and arguments on the command line, the return code of Petals CLI is 0.

h3. Return code on error about options or arguments on the command line

When there is an error about options or arguments on the command line, the return code of Petals CLI is 1.

h3. Return code on error about options and arguments of a command

h3. Options et arguments parsing

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

h3. Error management of a command set on the command line

If an error occurs during the execution of a command set on the command line:
* The command is interrupted.
* Petals CLI is interrupted with the return code 2.

h3. Error management of a command in interactive mode

If an error occurs during the execution of a command entered in interactive mode:
* The error message is displayed.
* Petals CLI is not interrupted, the user can enter other commands.

h3. 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 attribute {{{*}lastErrorCode{*}}}.
{code}
> ./petals-cli.sh - << EOF
deploy <artifact-url>
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.

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

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

h2. Connection options from the command line

All the required parameters for a JMX connection must be configurable on the command line as options:
{code}
> ./petals-cli.sh -h <host> -n <port> -u <user> -p <password> -c <command>
> ./petals-cli.sh -h <host> -n <port> -u <user> -p <password> -C
petals-cli@<host1>:<port1>>
{code}

> ./petals-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> connect <user1>:<password1>@<host1>:<port1>
Connected on <host1>:<port1> with '<user1>'
petals-cli> disconnect
petals-cli> connect
petals-cli> Would you like to connect to <default-user>:*****@<default-host>:<default-port>? (y/n)
y
petals-cli@<default-host>:<default-port>>
{code}

h2. Default connection

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

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

> ./petals-cli.sh -c stop
{code}
{tip}This is necessary to easily stop a local container{tip}
- In 'script' mode, the connection is establish on command 'connect' to <default-host>:<-default-port> with credentials '<default-user>/<default-pwd>'.
{code}
> ./petals-cli.sh - << EOF
connect
EOF
{code}

h2. Security

For security reasons, a Petals 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 CLI displays an error message.

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

Type 'help' for help.
------------------------------------------------------------------------------
petals-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 CLI will ask the user to type in the credentials.

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

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

petals-cli> Username: right-username
petals-cli> Password: wrong-pwd
Invalid credentials.
petals-cli> Retry? (y/n)
y

petals-cli> Username: right-username
petals-cli> Password: right-pwd
petals-cli@<default-host>:<-default-port>>
{code}


h1. Administration Commands

{code}
deploy <artifact-file> [<configuration-file> | <configuration-properties>]

{code}
deploy <maven-artifact> [<configuration-file> | <configuration-properties>]

deploy /tmp
EOF
> ./petals-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> deploy /tmp
Are you sure you want to deploy all artifacts of directory '/tmp'? (Y/n)

{code}
undeploy [ <artifact-file> | [<artifact-type> <artifact-id>] ]

undeploy
EOF
> ./petals-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> undeploy
Are you sure you want to undeploy all artifacts of the Petals node (Y/n) ?

petals-bc-soap Started BC
petals-se-bpel Started SE
soap-consume-provide Started SA
su-SOAP-EchoService-consume Started SU
su-SOAP-EchoService-provide Started SU

* Its JBI identifier.
* Its current status.
* Its type (SL, BC, SE, SA, SU).

* For a shared library:
** Its JBI identifier
** Its version, if available
** Extended information:
*** List of embedded libraries

* For a component (BC or SE):
** Its JBI identifier
** Its type: binding component or service engine
** Its version, if available
** Its state (loaded, installed, started, stopped, shutdown)
** Extended information:
*** List of embedded libraries of the boostrap classpath
*** List of embedded libraries of the runtime classpath

* For a service assembly:
** Its JBI identifier
** Its version, if available
** Its state (deployed, started, stopped, shutdown)
** List of embedded service-units (displayed using their JBI identifiers)
** Extended information:
*** For each service unit:
*** Its JBI identifier
*** Its version, if available

deploy /tmp/my-artifact.zip
exit lastErrorCode
EOF
{code}

deploy /tmp/my-artifact.zip
EOF
echo $?
0
{code}

h2. Working with the Container

Petals JBI Container 3.1.4-SNAPSHOT
Java(TM) SE Runtime Environment 1.6.0_26-b03
Linux 3.0.0-16-generic-pae
{code}

{code}

When connected to a container, it is possible to get information about the topology this node is part of.

{code}
petals-cli@host:port> topology-list
Domain: Domain 1
Subdomain: SubDomain 1
* Node1
** information

* Node2
** information

Subdomain: SubDomain 2
...
{code}

This command shows a set of Petals nodes, sorted by domain and sub-domains, each node having the following information:
* Container name
* Node type (master or slave)
* Host
* Node ports

petals-cli@host:port> properties-list
Key1: value1
Key2: value2

On a container, it is possible to change the level of a logger.
{code}
petals-cli@host:port> logger-set <logger-name> <level>
logger1
logger2
...
{code}

To get all the available loggers, use loggers without any argument.
{code}
petals-cli@host:port> loggers
logger1
logger2
...
{code}

You can also use a regular expression to filter the candiate results.
{code}
petals-cli@host:port> loggers <regular expression>
logger1
logger2
...
{code}

{tip}Auto-completion is available on logger names.{tip}

h2. Working with the Service Registry

{note}Qualified names, like service and interface names, are written as follows:\{namespace-uri\}local-part.{note}

Synchronization is done

<Progress Report (as a percentage)>
Synchronization is done
{code}

{note}Global synchronization is done in two passes:
* Each slave declares its end-points to the master node (n-1 synchronizations, where n is the number of nodes in the topology).
* Each slave gets the master end-points (start from the n-2 nodes until we get back to the first slave).
{note}

The response message is displayed in 'console' mode only.

<endpoint-name-2>: <endpoint-2-characteristics>
Services:
<service-name-1>:
<endpoints-list>
<service-name-2>:
<endpoints-list>
Interfaces:
<interface-name-1>:
<endpoints-list>
<interface-name-2>:
<endpoints-list>
{code}

where:
* <endpoint-name-x> is an endpoint name.
* <endpoint-x-characteristics> is the attributes of the endpoint, separated by comma: container identifier, component identifier, endpoint type.
* <service-name-x> is a service name.
* <interface-name-x> is an interface name.

Services:
<service-name-1>:
<endpoint-name>
<service-name-2>:
<endpoint-name>
Interfaces:
<interface-name-1>:
<endpoint-name>
<interface-name-2>:
<endpoint-name>
{code}