{section}
{column}

h1. Usage of Petals CLI

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

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

h1. Use cases

Petals CLI realizes the following use-cases.

h2. Petals CLI capabilities about script and shell usages

h3. Interactive console

Launching the 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>
{code}

-This command is wrapped by another shell: petals-cli-console.sh.- As it is not more usable than the option '-C' on command line, the wrapper script is removed. On Linux, a shell alias can be defined.

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

Launching the 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 the Petals CLI with the following command line executes commands of a Petals script:
{code}
> ./petals-cli.sh <filename>
> ./petals-cli.sh --file <filename>
{code}
{info}A Petals script is text file containing command supported by Petals CLI.{info}

h3. Execution of an inlined Petals script

Launching the Petals CLI with the following command line executes commands provided through the '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

h3. Getting help on command-line options and arguments

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

h3. Getting help on command from the command line

The help on a command can be get using the command '{{help}}'. A usage and a description of the command is displayed:
{code}
> ./petals-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 of the command
- {{<command-description}} is a text explaining the command

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

The list of available command can be get using the command '{{help}}' without argument:

The help on a command can be get using the command '{{help}}'. A usage and a description of the command is displayed:
{code}> ./petals-cli.sh -C

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 description>
>
{code}
where:
- {{<command>}} is the command for which we want to get help
- {{<command-arguments>}} is the list of arguments of the command
- {{<command-description}} is a text explaining the command


h2. Return code of Petals CLI

h3. Return code when all is ok

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 option or arguments on the command line

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

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

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

h2. Error management

h3. Options et argument parsing error management

If an error of parsing of options and/or arguments of the command line or commands, Petals CLI is interrupted with the right return code.

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 entered in interactive mode (mode 'console')

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 (mode 'script')

deploy <artifact-url>
isNoErrorReturned ? listartefacts : exit lastErrorCode
EOF
{code}
Note:
- the return values of command {{isParsingErrorReturned}}, {{isExecutionErrorReturned}} and {{isNoErrorReturned}} are re-intialized when invoking 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. Connection to a Petals node

h3. Connection options from the command line

All parameters needed to a JMX connection to a remote Petals node 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
Conected on <host1>:<port1> with <user1>
petals-cli>
{code}

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> open <user1>:<password1>@<host1>:<port1>
Conected on <host1>:<port1> with '<user1>'
petals-cli> close
petals-cli> open
Conected on localhost:7700 with 'petals'
{code}

h3. Default connection

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> open
Conected on localhost:7700 with 'petals'
{code}
- In mode 'command line', connexion parameter are mandatory
{code}
> ./petals-cli.sh -h <host> -n <port> -u <user> -p <password> -c <command>
{code}
- In mode 'script', the connexion is establish on command 'open' to localhost:7700 with credentials 'petals/petals'
{code}
> ./petals-cli.sh - << EOF
open
EOF
{code}

h2. Petals CLI commands

h3. Operating the JBI artifacts

h4. Installation/Deployment and start of an artifact in one command

Petals CLI is able to install/deploy and start a JBI artifact without distinction between shared-library, component and service assembly using the following command:
{code}
deploy <artifact-file> [<configuration-file> | <configuration-properties>]
{code}
where:
- {{<artifact-file>}} is the local file name or the URL of the artifact to install or deploy and start
- {{<configuration-file>}} is the local file name or the URL of the properties file used to configure the artifact. This argument is used only if the component is a component. It has no sens for other artifacts. This argument is exclusive with {{<configuration-properties>}}.
- {{<configuration-properties>}} is a list of '{{<property-name>=<property-value>}}', separated by space, where {{<property-name>}} is the name of the property to configure with {{<property-value>}}. This argument is used only if the component is a component. It has no sens for other artifacts. This argument is exclusive with {{<configuration-file>}}.

h4. Installation/Deployment of an artifact located into a Maven repository

Petals CLI is able to install/deploy and start an JBI artifact located into a Maven repository using the following command:
{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}

If the argument {{<artifact-file>}} of the command {{deploy}} is a local directory, all artifacts of the directory are deployed. In this case a confirmation is expected, except if the flag 'yes' is set on the command line. A confirmation message is displayed in the mode 'console', except is the flag 'yes' is set on the command line.

{code}
where:
- {{<artifact-file>}} is the local file name or the URL of the artifact to start
- {{<artifact-type>}} is the nature (SL, component, SA) of the artifact to start
- {{<artifact-id>}} is the JBI identifier of the artifact to start

{code}
where:
- {{<artifact-file>}} is the local file name or the URL of the artifact to stop
- {{<artifact-type>}} is the nature (SL, component, SA) of the artifact to stop
- {{<artifact-id>}} is the JBI identifier of the artifact to stop

h4. Uninstallation/Undeployment and stop of an artifact in one command

Petals CLI is able to stop and uninstall/undeploy a JBI artifact without distinction between shared-library, component and service assembly using the following command:
{code}
undeploy [ <artifact-file> | [<artifact-type> <artifact-id>] ]
{code}
where:
- {{<artifact-file>}} is the local file name or the URL of the artifact to undeploy

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) ?
{code}

If no arguments is set on command {{undeploy}}, all artifacts are undeployed. In this case a confirmation is expected, except if the flag 'yes' is set on the command line. A confirmation message is displayed in the mode 'console', except is the flag 'yes' is set on the command line.

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
{code}
where:
- {{<artifact-pattern>}} is an optional RegExp pattern to filter the content of the returned list. All JBI artifact returned must have a JBI identifier matching the pattern. If not pattern is defined, all installed artifacts are returned.
- {{<artifact-type>}} is one of the following values: SL, BC, SE, SA, SU, used to restrict the returned list
The command displays (caution to the padding) for each artifact:
- its JBI identifier
- its current status,
- its type (SL, BC, SE, SA, SU)

{code}
where:
- {{<artifact-file>}} is the local file name or the URL of the artifact to show

- for a shared library:
-- its JBI identifier
-- its version, if available
-- extended information:
--- list of embedded libraries
- for a component:
-- 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,
---- its target component ((displayed using its JBI identifier)

h3. Command '{{exit}}'

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

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

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

h4. Ending a flow of commands

When the end of a flow of commands is reached, if the last command is not '{{exit}}', the command '{{exit lastErrorCode}}' is implicitly executed:
{code}
> ./petals-cli.sh -y - << EOF
deploy /tmp/my-artifact.zip
EOF
echo $?
0
{code}

h3. Operating Petals CLI

h4. Getting the versions of the Petals CLI

To get the version of Petals CLI, the version of the JVM running Petals CLI, and its operating system, use the option '-V':
{code}
> ./petals-cli.sh -V
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
{code}

h3. Operating 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}

Are you sure you want to shutdown the container (Y/n) ?
{code}
A confirmation is expected, except if the flag 'yes' is set on the command line. A confirmation message is displayed in the mode 'console', except is the flag 'yes' is set on the command line.

h3. Operating the registry

Synchronization is done
{code}

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

Endpoints:
<endpoint-name-1>: <endpoint-1-characteristics>
<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,
- <endpoints-list> is the list of endpoint name implementing the interface or service.

Endpoints:
<endpoint-name>: <endpoint-characteristics>
Services:
<service-name-1>:
<endpoint-name>
<service-name-2>:
<endpoint-name>
Interfaces:
<interface-name-1>:
<endpoint-name>
<interface-name-2>:
<endpoint-name>
{code}
where:
- <endpoint-name> is the endpoint name used as filter,
- <endpoint-characteristics> is the attributes of the endpoint, separated by comma: container identifier, component identifier, endpoint type,
- <service-name-x> is the services associated to the specified endpoint,
- <interface-name-x> is the interfaces name associated to the specified endpoint.

Endpoints:
<endpoint-name-1>: <endpoint-1-characteristics>
<endpoint-name-2>: <endpoint-2-characteristics>
Services:
<service-name>:
<endpoints-list>
Interfaces:
<interface-name-1>:
<endpoints-list>
<interface-name-2>:
<endpoints-list>
{code}
where:
- <endpoint-name-x> are the endpoint names implementing the service,
- <endpoint-x-characteristics> is the attributes of the endpoint, separated by comma: container identifier, component identifier, endpoint type,
- <service-name> is the service full-name used as filter
- <interface-name-x> are the interfaces of the service
- <endpoints-list> is the list of endpoint name implementing the interface or service.

Endpoints:
<endpoint-name-1>: <endpoint-1-characteristics>
<endpoint-name-2>: <endpoint-2-characteristics>
Services:
<service-name-x>:
<endpoints-list>
Interfaces:
<interface-name>:
<endpoints-list>
{code}
where:
- <endpoint-name-x> are the endpoint names implementing the interface,
- <endpoint-x-characteristics> is the attributes of the endpoint, separated by comma: container identifier, component identifier, endpoint type,
- <service-name-x> are the service names implementing the interface,
- <interface-name> is the interface full-name used as filter,
- <endpoints-list> is the list of endpoint name implementing the interface or service.