## Galleon CLI tool
This command line tool (_bin/galleon.[sh|bat]_) allows you to provision/manage any products/installations that comply with galleon feature-packs.
Although being a generic tool, a builtin support is offered for products available from maven jboss community universe (eg: wildfly). +
Possible actions that you can operate from the tool: install, uninstall, check for updates, patch, update, undo last provisioning command.

### Feature-pack
A key concept in galleon system is the notion of feature-pack. A feature-pack is a content container. It can be a full product (eg: wildfly) 
or part of a product (eg: a wildfly subsystem packaged as a feature-pack). With the tool you are going to install/uninstall/update/... feature-packs. +
NB: A galleon installation can be composed of 1 or more feature-packs.

A feature-pack can be a file on your local file system or located inside a universe (a product catalog).

The tool helps you identify the feature-pack that you can use for the task you want to achieve. In order to take benefit of the full capabilities
offered by the tool, one needs to understand how products are identified inside a universe.

### Universe feature-pack location (FPL)
A feature-pack location (FPL) is the way to identify a product inside a universe without actually expressing any build numbers. 
A lot to commands require that you provide FPL. 

The main (non exhaustive) FPL syntax is: _<product>[@universe]:[version]/[qualifier]_ +
Some examples of FPL to identify wildfly products:

* _wildfly:current_ ==> Final (released) wildfly product current version
* _wildfly:current/alpha_ ==> The latest release of wildfly product current version that is at least of alpha quality.

The things to notice:

* Universe (from where the product comes from) is optional for products located in jboss maven community universe.
* No actual version nor build (eg: 1.0.0-Alpha1-SNAPHOT) is provided. The syntax of FPL is abstract it allows you to express a level of expected quality without
hard-coding any version number.
* Pointed by an FPL is an actual feature-pack artifact (a zipped file) that the tool will download/install,...
* A completer helps you compose FPL when the command you are calling expect one (eg: install).
 
For example, if one installs wildfly product using the following command:

_install wildfly:current/alpha --dir=myInstallation_ 

Then, later, when checking for updates or upgrading _myInstallation_ directory, 
the latest build that is at least of quality alpha will be used to update. 
If a final release is available then it will be installed when upgrading.

NB: Products being unique inside an installation, some commands (eg: _state update_) 
only require the product part (_<product>[@universe]_) of an FPL. For example:

_state update --products=wildfly_

### Universe feature-pack id (FPID)
A feature-pack id (FPID) is the way to identify a product inside a universe by expressing a build number. 
This is the syntax to use when you want to deal with specific builds of a product.

The FPID syntax is: _<product>[@universe]:[version]#[buildID]_ +
Some examples of FPID to identify wildfly products:

* _wildfly:current#1.0.0-Final_
* _wildfly:current#1.0.0-Alpha1_

The things to notice:

* Universe (from where the poduct comes from) is optional for products located in jboss maven community universe.
* Pointed by an FPID is an actual feature-pack artifact (a zipped file)
* A completer helps you compose your FPID when the command you are calling expect one (eg: install).
 
For example, to retrieve the informations of alpha1 build:

_feature-pack info wildfly:current#1.0.0-Alpha1_ 


### Installing a feature-pack

_install <[FPL|FPID] | [--file=<path to fp zip file>]> [--dir=<installation dir>] [--verbose] [feature-pack specific options]_

This creates a directory containing the installed feature-pack content (binaries, configs). +

NB: Using completion, when an installation directory has been identified, the options that
are specific to the feature-pack to install are proposed. When installing for the first time
a feature-pack this can take some time (a matter of few seconds up to minutes 
if the feature-pack needs to be downloaded from a remote location).

You can retrieve the set of feature-pack specific options without relying on completion, to do so call: +
_feature-pack info <[FPL|FPID] | [--file=<path to fp zip file>]> --type=options_ +
You can then use the listed options (if any) to customize your install command.

### Un-installing a feature-pack

_uninstall [FPID] [--dir=<installation dir>]_

This will remove the content installed by the feature-pack identified by the FPID.

NB: Completer proposes the FPID you can un-install from the installation (products and patches).

### Un-doing the last provisioning command

_state undo [--dir=<installation dir>] [--verbose]_

This will revert the installation to the previous installed state.

### Patching an installation

Use the _install_ command to patch an existing installation.

_install <[FPL|FPID] | [--file=<path to patch zip file>]> [--dir=<installation dir>] [--verbose] [feature-pack specific options]_

### Un-installing a patch

Use the _uninstall_ command to remove a given patch or use _state undo_ if the last provisioning command has been a patch installation.

### Checking for updates

_state check-updates [--dir=<installation dir>] [--include-all-dependencies] [--products=<list of products>]_

If no directory is provided, the current directory is used. If no products are provided, all installed products are checked for updates.

### Updating an installation

_state update [--dir=<installation dir>] [--include-all-dependencies] [--yes] [--products=<list of products>] [feature-pack specific options]_

Display the list of available updates/patches then update. If no directory is provided, the current directory is used. 
If _--yes_ is provided, the command will proceed without asking for confirmation.

NB: Using completion, when an installation directory has been identified, the options that
are specific to the installed feature-pack(s) are proposed. When updating an installation for the first time 
this can take some time (a matter of few seconds up to minutes if the feature-pack 
needs to be downloaded from a remote location).

You can retrieve the set of feature-pack specific options without relying on completion, to do so call: +
_state info [--dir=<installation dir>] --type=options_ +
You can then use the listed options (if any) to customize your update command.

### Observing an installation

_[my-dir]$ state info [--dir=installation] --type=[all|configs|dependencies|patches]_

Display the set of installed feature-packs FPID. In addition can display configurations, dependencies and patches. + 
NB: If some patches are applied, the applied patches information is displayed.

### Observing a feature-pack

_[my-dir]$ feature-pack info <[FPL|FPID] | [--file=<path to fp zip file>]> --type=[all|configs|dependencies|options]_

Display the FPID of a feature-pack. In addition can display dependencies, configurations 
and options usable when installing/provisioning/upgrading.

### Exporting an installation to xml

_[my-dir]$ state export <new generated xml file> --dir=<installation>_

###  Provisioning an installation from xml

_[my-dir]$ state provision <xml file> --dir=<target installation directory> [feature-pack specific options]_

NB: Using completion, when an installation directory has been identified, the options that
are specific to the feature-pack(s) located in the XML configuration file are proposed. 
When provisioning an installation for the first time this can take some time 
(a matter of few seconds up to minutes if the feature-pack needs to be downloaded from a remote location).

### Managing the history of an installation

By default the history keeps the state of the last 100 provisioning operations. This should be enough to cover 
simple undo of provisioned state. Nevertheless you can increase/decrease this
value by using the following command:
_state set-history-limit <history size limit> [--dir=<installation dir>]_

To retrieve the history size limit do:

_state get-history-limit [--dir=<installation dir>]_ +


### Exploring an installation or a feature-pack.

To explore an installation: +
_[my-dir]$ state explore --dir=installation_ +

To explore a feature-pack: +
_[my-dir]$ feature-pack explore <[FPL|FPID] | [--file=<path to fp zip file>]_ +

Once exploring, prompt, ls, cd and pwd commands are bound to the feature-pack (or installation) exposed file-system. +

_[/]$ ls +
configs +
feature-specs +
packages +
[/]$ state leave +
[my-dir]$_ +

The fs is composed of: +
/configs/final/<model>/<name>/<features> +
/feature-specs/<origin>/<feature-specs> +
/packages/<origin>/<packages> + 
Features and feature-specs are organized as a file system with containment. +
The set of available commands is limited when in “navigation mode”. 
Only “cd, ls, pwd and state info|leave” are available. Use state leave to exit this mode.

TIP: Use ‘ls’ to visualize any item. Use ‘cd’ to navigate to a given node.

### Searching the current state

When exploring, editing or composing a new state, one can search the packages and features.

_[/]$search [--query=<some text> | --package=<package name>]_

When searching with _--query_ all packages and features are looked-up for a match. If packages are matched, the features
that depend directly or indirectly on these packages will be shown in the result.

When searching with _--package_, the package completer can be used. The features that depend directly or 
indirectly on this package will be shown in the result.

### Creating a new state (or editing an existing state from an installation or provisioning XML file)

This allow to start from an empty installation or re-use an installation and iteratively add/suppress content. +

_[my-dir]$ state new  | state edit <path to installation | path to provisioning XML file> +
[/]$ <TAB> +
cd feature-pack ls pwd state +
[/]$ ls +
configs +
dependencies +
feature-specs +
packages_

The filesystem is similar to explore, with the addition of dependencies that contains full content of all added feature-packs. 

NB: Each action as the effect to build a runtime with the current state. The filesystem reflects the current state.

NB: Each action applied to a state in edition can be undone: _state undo_. Use _state leave_ to exit the composition mode.

NB: The set of exposed commands by completer is dynamic and is adjusted according to the current state.

### Managing universes
A universe can be added/removed to/from an existing installation or to a new/edited state. +
NB: In order to add/remove a universe to/from an installation you must first _cd_ in the directory of the installation. +
 
Add a named or default (without using the --name option) universe to the current provisioning state or installation. +
_[/]$ universe add [--name=<universe name>] --factory=<universe factory> --location=<universe location>_

Remove a named or default (without using the --name option) universe from the current provisioning state or installation. + 
_[/]$ universe remove [--name=<universe name>]_

### Listing products of universes

_[/]$ universe list_ + 

This command lists all the products and available builds present in all the installed universes.

You can search for products that match a given pattern using _--product=<pattern>_. +
For example: +
_[/]$ universe list --product=wildfly*_

### Exporting or provisioning the current state

At any time, one can export the provisioning XML file or directly provision from the current state:

_[/]$ state export <path to generated xml file> | state provision <dir of new installation>_

TIP: Use state export to validate that what you get in the XML is in sync with the expose state. In case you find something wrong, shout to me ;-)!

TIP: Exporting a state without any XML target file will display the XML content in the CLI console.

TIP: The command state info can be used to get high level information.

### Adding a feature-pack

_[/]$ fp add <FPL|FPID> [--default-configs-inherit] [--packages-inherit]_ +

By default nothing is inherited. Once at least one feature-pack has been added, configurations or packages can be handled. 

NB: A runtime based on the added full feature-pack is built in order to retrieve dependencies content and some completion content. This structure is cached for re-use.

### Removing a feature-pack

_[/]$ fp remove <FPL|FPID>_

### Including a default configuration

_[/]$ config include <model>/<name> [--origin=<fp origin>]_

Origin is optional, by default will be included from all fp that expose it.

### Removing an included default configuration

_[/]$ config remove-included <model>/<name> [--origin=<fp origin>]_

The completer only proposes the set of configurations that have been previously included. Same for fp.
Origin is optional, by default will be remove from all fp that include it.


### Excluding a default configuration

_[/]$ config exclude <model>/<name> [--origin=<fp origin>]_

Origin is optional, by default will be excluded from all fp that expose it.

### Removing an excluded default configuration

_[/]$ config remove-excluded <model>/<name> [--origin=<fp origin>]_

The completer only proposes the set of configurations that have been previously excluded. Same for fp.
Origin is optional, by default will be remove from all fp that exclude it.


### Reseting a configuration

_[/]$ config reset <model>/<name>_

The custom content of this configuration is removed.

NB: This has no effect on included/excluded configurations.

### Including a default package

_[/]$ packages include <fp origin>/<package name>_

### Removing an included default package

_[/]$ packages remove-included <package name> [--origin=<fp origin>]_

The completer only proposes the set of packages that have been previously included.
The origin is optional, the package will be removed from all fp that exclude it.

### Excluding a default package

_[/]$ packages exclude <fp origin>/<package name>_

### Removing an excluded default package

_[/]$ packages remove-excluded <package name> [--origin=<fp origin>]_

The completer only proposes the set of packages that have been previously excluded.
The origin is optional, the package will be removed from all fp that exclude it.

### Adding a new feature

_[/]$ feature add <config model/name> <path to feature-spec>  <dynamic set of feature param=<value>>_

For example: +
_feature add standalone/standalone.xml org.wildfly.core:wildfly-core-galleon-pack/interface --interface=toto --inet-address=127.0.0.1_

NB: All parameters are exposed as command option.
 
NB: All parameters that are not nillable and have no default values are required. The command being aborted if there are missing required parameters. 

NB: If the parameter is not present, its default value is injected when creating the feature.

NB: The current location (thanks to cd) is not yet taken into account when completing/adding the feature. That is a TODO.

NB: A feature with the same feature-id can’t exist. A single feature with the given feature-id per config.

### Removing a feature
_[/]$ feature remove <full path to feature inside a configuration>_

For example: +
_feature remove standalone/standalone.xml/interface/toto_




