manual/src/archives/1.3/asciidoc/shell-commands.adoc

//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
=== SSH Shell Commands

Apache Unomi provides its own Apache Karaf Shell commands to make it easy to control the application
lifecycle or perform queries or modifications on the internal state of the system.

All Apache Unomi-specific commands are namespaced and use the `unomi:` namespace. You can use the Apache Karaf Shell's
autocompletion to list all the commands available.

==== Using the shell

You can connect to the Apache Karaf SSH Shell using the following command:

    ssh -p 8102 karaf@localhost

The default username/password is karaf/karaf. You should change this as soon as possible by editing the `etc/users.properties` file.

Once connected you can simply type in :

    unomi:

And hit the <tab> key to see the list of all the available Apache Unomi commands. Note that some commands
are only available when the application is started.

You can also use the `help` command on any command such as in the following example:

```
karaf@root()> help unomi:migrate
DESCRIPTION
        unomi:migrate

    This will Migrate your date in ES to be compliant with current version

SYNTAX
        unomi:migrate [fromVersionWithoutSuffix]

ARGUMENTS
        fromVersionWithoutSuffix
                Origin version without suffix/qualifier (e.g: 1.2.0)
                (defaults to 1.2.0)
```
==== Lifecycle commands

The commands control the lifecycle of the Apache Unomi server and are used to migrate, start or stop the server.

.Table Lifecycle commands
|===
|Command|Arguments|Description

|migrate
|fromVersion
|This command must be used only when the Apache Unomi application is NOT STARTED. It will perform migration of the data stored in ElasticSearch using the argument fromVersion as a starting point.

|stop
|n/a
|Shutsdown the Apache Unomi application

|start
|n/a
|Starts the Apache Unomi application. Note that this state will be remembered between Apache Karaf launches, so in general it is only needed after a first installation or after a `migrate` command

|version
|n/a
|Prints out the currently deployed version of the Apache Unomi application inside the Apache Karaf runtime.
|===

==== Runtime commands

These commands are available once the application is running. If an argument is between brackets [] it means it is optional.

.Table Runtime commands
|===
|Command|Arguments|Description
|rule-list
|[--csv]
|Lists all the rules registered in the Apache Unomi server. If you add the "--csv" option the list will be output
as a CSV formatted table
|rule-view
|rule-id
|Dumps a single rule in JSON. The rule-id argument can be retrieved from the `rule-list` command output.
|rule-reset-stats
|n/a
|Resets the rule statistics. This is notably useful when trying to understand rule performance and impact
|event-tail
|n/a
|Dumps any incoming events to the Apache Unomi server to the console. Use CTRL+C to exit tail
|event-view
|event-id
|Dumps a single event in JSON. The `event-id` can be retrieved from the event-tail command output.
|action-list
|[--csv]
|Lists all the rule actions registered in the Apache Unomi server. This command is useful when developing plugins to
check that everything is properly registered. If you add the "--csv" option the list will be output
                                              as a CSV formatted table
|action-view
|action-id
|Dumps a single action in JSON. The action-id argument can be retrieved from the `action-list` command output.
|profile-list
|[--csv]
|List the last 10 modified profiles. If you add the "--csv" option the list will be output
                                     as a CSV formatted table
|profile-view
|profile-id
|Dumps a single profile in JSON. The profile-id argument can be retrieved from the `profile-list` command output.
|segment-list
|[--csv]
|Lists all the segments registered in the Apache Unomi server. If you add the "--csv" option the list will be output
                                                               as a CSV formatted table
|segment-view
|segment-id
|Dumps a single segment in JSON. The segment-id argument can be retrieved from the `segment-list` command output.
|session-list
|[--csv]
|Lists the last 10 sessions by last event date. If you add the "--csv" option the list will be output
                                                as a CSV formatted table
|session-view
|session-id
|Dumps a single session in JSON. The session-id argument can be retrieved from the `session-list`, `profile-list` or
 `event-tail` command output.
|deploy-definition
|[bundleId] [type] [fileName]
|This command can be used to force redeployment of definitions from bundles. By default existing definitions will not
be overriden unless they come from SNAPSHOT bundles. Using this command you can override this mechanism. Here are some
examples of using this command: `unomi:deploy-definition 175 rule *` will redeploy all the rules provided by bundle with id 175. If you launch the command without any arguments you will get prompts for what you want to deploy from which bundle

|===