{section}
{column}

usage: Petals JMX Command Line Interface

[-d] [-y] [-h <host> -n <port> | -h <host> -n <port> -u <user> -p <password> | -a
<alias>] [-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.
-H,--help Print this help message and exit.
-h,--host <host> JMX host of the remote petals ESB.
-n,--port <port> JMX port of the remote petals ESB.
-p,--password <password> JMX password of the remote petals ESB.
-u,--user <user> JMX user of the remote petals ESB.
-V,--version Print the version number and exit.
-y,--yes Enable automatic confirmation ('yes' flag)

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 ESB node.
deploy Deploy and start a JBI artifact.
disconnect
Disconnect from a petals container.
exit Exit this shell.
help Display this help message or help for a specific command.
list List JBI artifacts name and current status.
load Load properties from files.
logger-set
Set the specified level to the specified logger.
loggers Return all the loggers.
print Print a message.
properties-list
Get the values defined in its server.properties file.
pwd Print the working directory.
endpoint-list
List the entries of the endpoint directory.
set Assign a value to the system property named key.
show Print informations about a JBI artifact.
start-artifact
Start a JBI artifact.
stop Stop the container.
stop-artifact
Stop a JBI artifact.
system Execute system command.
topology-list
Get information about the topology this node is part o.
undeploy Stop and uninstall or undeploy JBI artifacts.
version Print version informations about petals container.

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

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

h1. Use Cases

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

{code}

> ./petals-cli.sh --file <filename>

> 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 '_\-H_' option. A text containing options, arguments and available commands is displayed according to the usage defined above.
{code}
> ./petals-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-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-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>

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

Petals ESB Command Line Interface 2.2.0
OpenJDK Runtime Environment 1.7.0_79-b14
Linux 3.19.0-30-generic
{code}

{code}

h3. Listing available variables

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

Type 'help' for help.
------------------------------------------------------------------------------
petals-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
env:PETALS_CLI_PREFS=/home/cdeneux/.petals-cli/petals-cli.default
...
{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-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> set my-property-name=value

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

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-cli.sh -C

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

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

|| OS/Distribution || System level file ||
| Linux/Debian-based distribution | {{/etc/petals-cli/petals-cli.default}} |
| Windows | {{%PETALS_CLI_HOME%\conf\petals-cli.default}} |

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

The preferences files contain a set of keys in several sections:

** *<alias>.port*: the JMX port of the default Petals node (required).

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

{note}In a production environment, we discourage setting passphrase at alias level to increase the security.{note}

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

# The connection properties of the 1st server
default.host = localhost
default.port = 7700
default.username = petals
default.password = petals
default.passphrase = petals

{tip}
You can [write your own command|#add_your_own_command]
{tip}

h1. Connection to a Petals node

h2. Connection options from the command line

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

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

{tip}The arguments {{-h}}, {{-p}}, {{-u}}, {{-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-cli.sh -C

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

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

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> connect -y
petals-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-cli.sh -h localhost -n 7700 -u petals -p petals -c -- stop
> ./petals-cli.sh -a default -c -- stop
{code}

{tip}This is necessary to easily stop a local container{tip}

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-cli.sh - << EOF
connect
EOF
{code}

> ./petals-cli.sh -C

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

> ./petals-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> connect
No default connection is available. Use 'help connect' for more information.
{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}

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 *user* was specified for a server.
{quote}The credentials for '<alias>' are invalid: add the password or remove the user.{quote}

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

h1. Administration Commands

h2. Working with JBI artifacts

h3. Artifact lifecycle managed by PetalsCLI

{gliffy:name=Artifact lifecycle of PetalsCLI|align=center|version=4}

{code}
where:
* *<artifact-file>* is the local file name or the URL correctly encoded of the artifact to install or deploy and start
* *<configuration-file>* is the local file name or the URL correctly encoded of the properties file used to configure the artifact. This argument is used only if the artifact is a component. It has no sense for other artifacts. This argument is exclusive with {{<configuration-properties>}}.
* *<configuration-properties>* is a list of '_<property-name>=<property-value>_', separated by a comma, where _<property-name>_ is the name of the property to configure with _<property-value>_. This argument is used only if the artifact is a component. It has no sense for other artifacts. This argument is exclusive with *<configuration-file>*.

If the flag {{\-s,\-\-skip-startup}} is set, the start-up of the artifact is skipped, the artifact is only deployed.

{warning}Due to a limitation with the underlying library used to implement CLI, it is necessary to have a space between {{-D}} and its argument! (see [PETALSESBCLI-150|https://jira.petalslink.com/browse/PETALSESBCLI-150] for details){warning}

{tip}
Maven URLs are supported by this command: {{deploy -u mvn:org.ow2.petals/petals-se-xslt/LATEST/zip}}.
{tip}

* a component:
** if its component installer is already loaded (the component is not installed), then the command '{{deploy}}' will unload the component installer, reload a new one and continue the lifecycle (configuration, installation and start),
** if the component is installed:
*** if the component is shutdown, then the command '{{deploy}}' will uninstall the component, unload the component installer, reload a new one and continue the lifecycle (configuration, installation and start),
*** otherwise an error occurs, use command '{{undeploy}}' to fix it.
* a service assembly:
** if the SA is already deployed and in state 'SHUTDOWN', then the command '{{deploy}}' will undeploy the service assembly, before to re-deploy a new one,
** otherwise an error occurs, use command '{{undeploy}}' to fix it.
* a deployable service unit:
** a service assembly is created from the deployable service unit,
** next, the service assembly is deployed usually.

h3. Bulk Deployment and Start

To deploy and start several artifacts in one command, just put them in a local directory and execute the command '_deploy_':
{code}
deploy -b,--bulk <url|file> [-s,--skip-startup]
{code}
{code}
> ./petals-cli.sh -y - << EOF
deploy -b file:///tmp
EOF
> ./petals-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> deploy -b /tmp
{code}

If the argument _<artifact-file>_ of the '_deploy_' command is a local directory, all artifacts of the directory are deployed.

If the flag {{\-s,\-\-skip-startup}} is set, the start-up of the artifact is skipped, the artifact is only deployed.

{note}Only the protocol 'file' is available.{note}

h3. Starting an Artifact

An artifact can be started by using the '_start-artifact_' command:
{code}
> ./petals-cli.sh -c -- start-artifact [ -u <artifact-file> | -a <artifact-id> [-t <artifact-type>] ]
{code}
where:
* *<artifact-file>* is the local file name or the URL correctly encoded of the artifact to start.
* *<artifact-type>* is the nature (SL, component, SA) of the artifact to start. Accepted values are: SL, BC, SL, SA.
* *<artifact-id>* is the JBI identifier of the artifact to start.

{tip}
Maven URLs are supported by this command: {{start-artifact -u mvn:org.ow2.petals/petals-se-xslt/LATEST/zip}}.
{tip}

{tip}Auto-completion is available on artifacts IDs, artifact file names and artifact types. The auto-completer for artifact identifiers displays only artifacts in state STOPPED or SHUTDOWNED.{tip}

If the artifact to start is a component or a service assembly, the command '{{start-artifact}}' will succeed only if the artifact state on Petals ESB side is 'STOPPED' or 'SHUTDOWN', otherwise on error will occur.

If you want to start a deployable service unit, you must start the associated service assembly that was created during the deployment of the service unit.

h3. Stopping an artifact

An artifact can be stopped by using the command '_stop\-_{_}artifact_':
{code}
> ./petals-cli.sh -c -- stop-artifact [ -u <artifact-file> | -a <artifact-id> [-t <artifact-type>] ]
{code}
where:
* *<artifact-file>* is the local file name or the URL correctly encoded of the artifact to stop.
* *<artifact-type>* is the nature (SL, component, SA) of the artifact to stop. Accepted values are: SL, BC, SL, SA.
* *<artifact-id>* is the JBI identifier of the artifact to stop.

{tip}Auto-completion is available on artifacts IDs, artifact file names and artifact types. The auto-completer for artifact identifiers displays only artifacts in state STARTED.{tip}

{tip}
Maven URLs are supported by this command: {{stop-artifact -u mvn:org.ow2.petals/petals-se-xslt/LATEST/zip}}.
{tip}

If the artifact to deploy is a component or a service assembly, the command '{{stop-artifact}}' will succeed only if the artifact state on Petals ESB side is 'STARTED', otherwise on error will occur.

If you want to stop a deployable service unit, you must stop the associated service assembly that was created during the deployment of the service unit.

{code}
where:
* *<artifact-file>* is the local file name or the URL correctly encoded of the artifact to undeploy.
* *<artifact-id>* is the JBI identifier of the artifact to undeploy.
* *<artifact-type>* is the nature (SL, component, SA) of the artifact to undeploy. Accepted values are: SL, BC, SL, SA.
* *<artifact-version>* is the artifact version to limit artifacts matching other criteria. Supported only for SL.

{tip}
Maven URLs are supported by this command: {{undeploy -u mvn:org.ow2.petals/petals-se-xslt/LATEST/zip}}.
{tip}

{tip}Auto-completion is available on artifacts IDs, artifact file names and artifact types.{tip}

No lifecycle error can occur. Whatever the artifact state, the command 'undeploy' will adapt to it to realize the undeployment. In particular, if the artifact is in state 'STOPPED', it will be undeployed without confirmation and the user will be responsible to re-deploy it.

If you want to undeploy a deployable service unit, you must undeploy the associated service assembly that was created during the deployment of the service unit.

h3. Bulk Undeployment and Stop

The undeployment command is able to stop and uninstall/undeploy several JBI artifact in one shoot using the bulk mode:

{code}
undeploy [ -b [<artifact-directory>] ] [ -y ]
{code}
where *<artifact-directory>* is a local directory name or the URL containing archives of artifacts to undeploy. If not set set, all JBI artifacts are stopped and undeployed/uninstalled.

A confirmation is expected, except if the '_yes_' flag is set on the command line or as command argument, otherwise an error will occur.
A confirmation message is displayed in the console mode, except if the '_yes_' flag is set on the command line or as command argument.
{code}
> ./petals-cli.sh -y -c -- undeploy -b
> ./petals-cli.sh -c -- undeploy -b -y
> ./petals-cli.sh -c -- undeploy -b
ERROR on command 'undeploy': A confirmation is required. Use option: : '-y'
{code}

If the directory, containing artifacts to undeploy, contains an artifact that is not deployed, a warning is displayed, no error occurs and the undeployment of other artifacts continues.
If an error occurs during the undeployment of an artifact, the bulk undeployment is interrupted.

h3. Showing installed JBI artifacts

All the installed JBI artefacts can be listed using the command '_list \[-p <artifact-pattern> \] \[-t artifact-type\]_':
{code}
> ./petals-cli.sh -c -- list
petals-sl-mysql(1.0.0) Installed SL
petals-bc-soap Loaded BC
petals-se-bpel Started SE
soap-consume-provide Started SA
su-SOAP-EchoService-consume SU
su-SOAP-EchoService-provide SU
{code}
where:
* {color:#000000}*<artifact-pattern>*{color} {color:#000000}is an optional RegExp pattern to filter the content of the returned list. All the returned JBI artifacts must have a JBI identifier matching the pattern. If no pattern is defined, all the installed artifacts are returned.{color}
* {color:#000000}*<artifact-type>*{color} {color:#000000}is one of the following values: SL, BC, SE, SA, SU, used to restrict the returned list.{color}

The returned list is ordered:
* firstly, according to the artifact type: SL, BC, SE, SA, SU,
* and secondly the alphabetical order is applied.

For each artifact, the command displays (caution to the padding):
* Its JBI identifier. If the JBI artifact is a shared library, the JBI identifier is displayed according to the following pattern: {{name(version)}}
* Its current status:
** {{Loaded}}, available only for component, the installer is loaded but the component is not installed
** {{Started}}
** {{Stopped}}
* Its type (SL, BC, SE, SA, SU).

{tip}As the SU lifecycle can't be modified through the JMX API, there is no interest to display the SU status (it's the same as the status of its SA).{tip}

h3. Getting information about an Artifact

Information about a JBI artifact can be got with the '_show_' command:
{code}
> ./petals-cli.sh -c -- show [-e] [ -u <artifact-file> | -a <artifact-id> [-t <artifact-type>] [-v <artifact-version>] ]
{code}
where:
* *<artifact-file>* is the local file name or the URL correctly encoded of the artifact to show.
* *<artifact-id>* is the JBI identifier of the artifact to show.
* *<artifact-type>* is the nature (SL, component, SA) of the artifact to show. Accepted values are: SL, BC, SL, SA, SU.
* *<artifact-version>* is the artifact version to limit artifacts matching other criteria. Supported only for SL.

The '-e' option displays extended information.

Displayed information includes:

* For a shared library:
** Its JBI identifier
** The version of the shared library if available, extracted from its JBI descriptor
** If the shared library was built with Maven, its Maven version extracted from Maven metadata
** {color:#ff0000}Extended information:{color}
*** {color:#ff0000}List of embedded libraries (coming next){color}


* For a component (BC or SE):
** Its JBI identifier
** Its type: binding component or service engine
** If the component was built with Maven, its Maven version extracted from Maven metadata
** Its state (not-loaded, loaded, installed, started, stopped, shutdown)
** {color:#ff0000}Extended information:{color}
*** {color:#ff0000}List of embedded libraries of the boostrap classpath(coming next){color}
*** {color:#ff0000}List of embedded libraries of the runtime classpath(coming next){color}
*** {color:#ff0000}List of needed shared-libraries, for each shared-library(coming next):{color}
**** {color:#ff0000}Its JBI identifier{color}
**** {color:#ff0000}The version of the shared library if available, extracted from its JBI descriptor{color}


* For a service assembly:
** Its JBI identifier
** If the service-assembly was built with Maven, its Maven version extracted from Maven metadata
** Its state (not-deployed, deployed, started, stopped, shutdown)
** List of embedded service-units (displayed using their JBI identifiers)
** Extended information (replace the previous list of embedded service-units):
*** For each service unit embedded:
*** Its JBI identifier
*** Its target component (displayed using its JBI identifier)

{tip}Auto-completion is available on artifacts IDs, artifact file names and artifact types.{tip}

{tip}
Maven URLs are supported by this command: {{show -u mvn:org.ow2.petals/petals-se-xslt/LATEST/zip}}.
{tip}

h3. Reloading the external configuration of a JBI component

Each Petals CDK-based JBI component includes a parameter named '{{properties-file}}' containing placeholders to configure some parameters at service unit level. These placeholder values can be reloaded without stopping anything using the command '_reload\-_{_}configuration_':
{code}
> ./petals-cli.sh -c -- reload-configuration [ -u <artifact-file> | -a <artifact-id> ]
{code}
where:
* *<artifact-file>* is the local file name or the URL correctly encoded of the JBI component artifact for which the configuration must be reloaded,
* *<artifact-id>* is the JBI identifier of JBI component artifact for which the configuration must be reloaded.

{tip}Auto-completion is available on JBI component artifact identifiers and artifact file names. The auto-completer for artifact identifiers displays only artifacts in state STARTED or STOPPED.{tip}

h3. Interrupting a flow of commands

A flow of commands can be interrupted by using the '_exit_' command. If a number is set as argument, it is used as return code. The argument '_lastErrorCode_' is used as return code value of the last executed command. Otherwise, 0 is returned to the shell.
{code}
> ./petals-cli.sh -y - << EOF
deploy /tmp/my-artifact.zip
exit lastErrorCode
EOF
{code}

h3. Ending a flow of commands

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

h2. Working with the Container

h3. Getting the versions related to a Petals node

To get the version of a Petals node, the version of the JVM running Petals node, and its operating system, use the '_version_' command:
{code}
> ./petals-cli.sh -c -- version
Petals JBI Container 5.0.0-M1
OpenJDK Runtime Environment 24.79-b02 Oracle Corporation
Linux 3.19.0-30-generic amd64
{code}

h3. Stopping the container

The container can be stopped by using the command '_stop_':
{code}
> ./petals-cli.sh -c -- stop
{code}

h3. Shutdowning the container

The container can be shut-downed by using the command '_stop_' and the parameter '_\--shutdown_'.
{code}
> ./petals-cli.sh -C
petals-cli@host:port> stop --shutdown
Are you sure you want to shutdown the container? (y/n)
{code}

A confirmation is expected, except if the '_yes_' flag is set on the command line or as command argument, otherwise an error will occur.
A confirmation message is displayed in the console mode, except if the '_yes_' flag is set on the command line or as command argument.
{code}
> ./petals-cli.sh -y -c -- stop --shutdown
> ./petals-cli.sh -c -- stop --shutdown -y
> ./petals-cli.sh -c -- stop --shutdown
ERROR on command 'stop': A confirmation is required. Use option: : '-y'
{code}

h3. Getting the server properties

When connected to a container, it is possible to get all the values defined in its *server.properties* file.

{code}
petals-cli@host:port> properties-list
Key1: value1
Key2: value2
...
{code}
where "keyN" and "valueN" are the keys and values defined in the *server.properties* file of this container.

h3. Changing logger levels

On a container, it is possible to change the level of a logger.
{code}
petals-cli@host:port> logger-set -n <logger-name> -l <level>
The log level was succesfully changed.
{code}

In case of error, the error message is "The log level could not be changed.", followed by a detailed message (e.g. "WARN is not a valid log level").

\\
To get all the available loggers with their level, use the command {{loggers}} without any argument.
{code}
petals-cli@host:port> loggers
<logger-name-1> <level>
<logger-name-2> <level>
...
{code}

\\
You can also use a regular expression to filter the candidate results.
{code}
petals-cli@host:port> loggers -p <regular expression>
<logger-name-1> <level>
<logger-name-2> <level>
...
{code}

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

h2. Working with the Topology

h3. Getting the topology

h4. Getting the topology only

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

{code}
petals-cli@host:port> topology-list
Domain: Domain 1
* Container: Node1 (Reachable)
** information

* Container: Node2 (Unreachable)
** information

...
{code}

Sensible information as credentials are returned only if a security passphrase is provided. This passphrase can be provided using the command option '-p'. Or, if you used an alias (including the default alias) to connect to the remote Petals container, the passphrase set at alias level ({{<alias>.passphrase}}) will be used automatically if defined.
{code}
petals-cli@host:port> topology-list -p mypassphrase
Domain: Domain 1
* Container: Node1 (Reachable)
** information including credentials
{code}
{note}In a production environment, we discourage setting passphrase at alias level to increase the security{note}

This command shows a set of Petals nodes of the same domain, each node having the following information:
* Container name,
* Container state (possible values are: {{Reachable}}, {{Unreachable}}, {{Unknown}}),
* Host,
* Node ports,
* Node credentials (only if the security passphrase is provided and correct).

h4. Getting the topology with JBI artifacts deployed

All JBI artifacts deployed on each Petals container of the topology can be displayed using the option '{{-a | --artifacts}}'. With this option the following JBI artifacts are returned: shared libraries, components and service assemblies.
{note}The pass-phrase argument is required to retrieve JBI artifacts deployed on each Petals container.{note}
{code}
petals-cli@host:port> topology-list -a -p mypassphrase
Domain: Domain 1
* Container: Node1 (Reachable)
** container information
** shared library informations
** component informations
** service assembly information

* Container: Node2 (Reachable)
** container information
** shared library informations
** component informations
** service assembly information

* Container: Node2 (Unreachable)
** container information

...
{code}

Information returned are:
* for share libraries: name and version,
* for components: name and state ({{Loaded}}, {{Started}} or {{Stopped}}),
* for service assemblies: name and state ({{Started}} or {{Stopped}}).

{note}To get information about JBI artifacts, the Petals container holding them must be reachable. So if one container can not be reached, no error is returned and no information about shared-libray, component and service-assemblies is displayed for this container.{note}

h4. Filtering

The content of the topology can be limited to some containers using the filter '{{-c <container-name-regexp>}}', where _{{container-name-regexp}}_ is a regexp identifying the containers to displayed:
{code}
petals-cli@host:port> topology-list -c Node1
Domain: Domain 1
* Container: Node1 (Reachable)
** information of Node1
{code}

{tip}The auto-completion of the filter '{{-c}}' proposes the container names of the topology.{tip}

h3. Moving or attaching a container to another domain

A running container can be moved to another domain, using the command '_move-container_':
{code}
>./petals-cli.sh -C
petals-cli@host:port> move-container [--target-domain <domain-0> [--target-host <localhost>] [--target-port <7700>] [--target-user <petals>] [--target-pwd <petals>] --target-pass-phrase <target-pass-phrase>]
Are you sure you want to move the current container ? (y/n)
{code}

* *--target-port*: the JMX port of the container of the target domain. Default value: {{7700}},
* *--target-user*: the JMX username of the container of the target domain. Default value: {{petals}},
* *--target-pwd*: the JMX password of the container of the target domain. Default value: {{petals}},
* *--target-pass-phrase*: the security pass-phrase to access sensible information

Note that the domain name is only used to verify the consistency of the move: in the end, what matters is that the container will be moved to the same domain as the target container that is contacted using the JMX connection informations.

A confirmation is expected, except if the '_yes_' flag is set on the command line or as command argument, otherwise an error will occur.
A confirmation message is displayed in the console mode, except if the '_yes_' flag is set on the command line or as command argument.
{code}
> ./petals-cli.sh -y -c -- move-container ...
> ./petals-cli.sh -c -- move-container -y ...
> ./petals-cli.sh -c -- move-container
ERROR on command 'move-container': A confirmation is required. Use option: : '-y'
{code}


h3. Detaching a container from domain

A running container can be detached from a domain, using the command '_move-container_':
{code}
>./petals-cli.sh -C
petals-cli@host:port> move-container
Are you sure you want to detach the current container ? (y/n)
{code}

A confirmation message is displayed in the console mode, except if the '_yes_' flag is set on the command line or as command argument.
{code}
> ./petals-cli.sh -y -c -- move-container ...
> ./petals-cli.sh -c -- move-container -y ...
> ./petals-cli.sh -c -- move-container
ERROR on command 'move-container': A confirmation is required. Use option: : '-y'
{code}

h2. Working with the endpoint directory

h3. Showing the endpoint directory's full content

The full content of the endpoint directory can be dumped by using the '_endpoint-list_' command:
{code}
petals-cli> endpoint-list
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.

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

h4. Filtering the endpoint directory's full content

The content of the endpoint directory can be dumped by using the '_endpoint-list_' command.
It is however possible to filter the dumped result.
{code}
petals-cli> endpoint-list [-e <endpoint-name-regexp>] [-s <service-name-regexp>] [-i <interface-name-regexp>] [-c <container-name-regexp>]
{code}

where:
* *<endpoint-name-regexp>* is a regular expression used as filter on the full end-point name,
* *<service-name-regexp>* is a regular expression used as filter on the full service name,
* *<interface-name-regexp>* is a regular expression used as filter on the full interface name,
* *<container-name-regexp>* is a regular expression used as filter on the container name on which the endpoints are deployed.

The parameter order (endpoint, service, interface) does not matter.
All are optional. If none is specified, the entire endpoint directory content is dumped.

{note}
The \{ and \} are special in Java's regex dialect: they are the opening and closing tokens for the repetition quantifier {{\{n,m\}}} where {{n}} and {{m}} are integers. Hence the error message: "Illegal repetition".

You should escape them: {code}\{http://petals.ow2.org/\}Service{code}
{note}

h4. Controlling the output of the endpoint directory content dumped

The output of the command 'endpoint-list', defined below, is composed of 3 parts:
* endpoints, under the header '{{Endpoints:}}',
* services, under the header '{{Services:}}',
* interfaces, under the header '{{Interface:}}'.

You can select the parts to display one by one using:
{code}
petals-cli> endpoint-list [--output-endpoints] [--output-services] [--output-interfaces]
{code}

where:
* {{--output-endpoints}} selects the part about endpoints,
* {{--output-services}} selects the part about services,
* {{--output-interfaces}} selects the part about interfaces.

If only one of these flags is set, its header will not be displayed. If none of these flags is set, all 3 parts are displayed.

{code:title=Sample #1}
petals-cli@localhost:7700>endpoint-list -e HelloEndpoint-TargetContainer[01]
Endpoints:
HelloEndpoint-TargetContainer0: target-container-0,petals-se-pojo,INTERNAL
HelloEndpoint-TargetContainer1: target-container-1,petals-se-pojo,INTERNAL
Services:
{http://petals.ow2.org/}HelloService0:
HelloEndpoint-TargetContainer0
{http://petals.ow2.org/}HelloService1:
HelloEndpoint-TargetContainer1
Interfaces:
{http://petals.ow2.org/}HelloPortType:
HelloEndpoint-TargetContainer0 HelloEndpoint-TargetContainer1
{code}
{code:title=Sample #2}
petals-cli@localhost:7700>endpoint-list -e HelloEndpoint-TargetContainer[01] --output-endpoints
HelloEndpoint-TargetContainer0: target-container-0,petals-se-pojo,INTERNAL
HelloEndpoint-TargetContainer1: target-container-1,petals-se-pojo,INTERNAL
{code}
{code:title=Sample #3}
petals-cli@localhost:7700>endpoint-list -e HelloEndpoint-TargetContainer[01] --output-endpoints --output-interfaces
Endpoints:
HelloEndpoint-TargetContainer0: target-container-0,petals-se-pojo,INTERNAL
HelloEndpoint-TargetContainer1: target-container-1,petals-se-pojo,INTERNAL
Interfaces:
{http://petals.ow2.org/}HelloPortType:
HelloEndpoint-TargetContainer0 HelloEndpoint-TargetContainer1
{code}
{code:title=Sample #4}
petals-cli@localhost:7700>endpoint-list -e HelloEndpoint-TargetContainer[01] -s {http://petals.ow2.org/}HelloService0 --output-endpoints --output-services
Endpoints:
HelloEndpoint-TargetContainer0: target-container-0,petals-se-pojo,INTERNAL
HelloEndpoint-TargetContainer1: target-container-1,petals-se-pojo,INTERNAL
Services:
{http://petals.ow2.org/}HelloService0:
HelloEndpoint-TargetContainer0
{code}
{code:title=Sample #5}
petals-cli@localhost:7700>endpoint-list -e HelloEndpoint-TargetContainer[01] -s {http://petals.ow2.org/}HelloService0 --output-services
{http://petals.ow2.org/}HelloService0:
HelloEndpoint-TargetContainer0
{code}
{code:title=Sample #6}
petals-cli@localhost:7700>endpoint-list -e HelloEndpoint-TargetContainer[01] --output-services
{http://petals.ow2.org/}HelloService0:
HelloEndpoint-TargetContainer0
{http://petals.ow2.org/}HelloService1:
HelloEndpoint-TargetContainer1
{code}

h3. Checking a SSL connection establishment

The command *{{check-ssl-handshake}}* provides a way to check the establishment of a SSL connection:
{code}
USAGE:
check-ssl-handshake usage: check-ssl-handshake [-h <host>] [-k <keystore-file>] [-p <port>]
[--trust-all-certificates] [-u <keystore-file>]


DESCRIPTION:
Check SSL handshake to a geiven serverDeploy and start a JBI artifact

OPTIONS DESCRIPTION:
-h,--host <host> Hostname to connect. Default
value used: localhost
-k,--keystore-file <keystore-file> Keystore file containing
certificates. Default
keystore: the JVM one
-p,--port <port> Port on host to connect.
Default value used: 443
(HTTPS)
--trust-all-certificates Trust all certificates.
Certificate validation is
disabled.
-u,--keystore-passphrase <keystore-file> Passphrase to open the
keystore containing
certificates.
{code}

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

As an example,

{code}
petals-cli> system pwd

{info}
A system command having arguments can also be enclosed with quotes:
{code}
petals-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-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-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}

{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_CLI_HOME/bin/petals-cli.sh}}' or '{{%PETALS_CLI_HOME%\bin\petals-cli.bat}}'. An sample configuration is available in file '{{$PETALS_CLI_HOME/conf/petals-cli-logging-sample.properties}}'

{anchor:add_your_own_command}

To create a new custom command, just create a new Java class that *IMPLEMENTS* the interface {{org.ow2.petals.cli.api.command.Command}}.

h1. Known Problems

h2. Error about missing options

For commands requiring at least one option, an error can occur if the operand flag ({{'--'}}) is missing:
{code}
> ./petals-cli.sh -h localhost -n 7700 -u petals -p petals -c -- deploy -u file:///.../my-archive.zip
ERROR on command 'deploy': Missing option(s):b, u
usage: deploy [-b <url> | -u <url>] [-D

{code}
By default, Petals ESB listens JMX connection from {{localhost}}, that's why you get the error. Update the host name of the Petals ESB in its topology configuration file to solve the problem.
* a mistake in your *network configuration* at system level: