CLI Documentation
This is the updated version (LiveRebel 1.1+) of the Command Line Interface (CLI) reference of LiveRebel Command Center. In this article we will show basic usage and describe properties of all commands that help you manage Command Center through the CLI.
LiveRebel download archive comes with utilities that are available from the bin folder. To access the CLI we will use the lr-cli.sh script (Windows equivalent is lr-cli.cmd). With this tool you can manage most of the LiveRebel functionality from the command line.
To run the CLI tool you will either need the username and password of a user in the LiveRebel Command Center or a security token for a user. To find out the token of your user navigate to your profile page (in LiveRebel Command Center in the top right there is your username that you can click) and your security token is displayed there. See the screenshots for more details.
Access your profile from the top right
Your authentication token on profile page
If you know LiveRebel Command Center url and user credentials (either an username/password pair or an authentication token) you can use lr-cli.sh script to manage the the following aspects of your LiveRebel Command Center.
Important note: you can provide lr-cli.properties file with Command Center url and credentials, and omit this information from every command execution. Just put the following file near the lr-cli script:
> cat lr-cli.properties url=localhost:9001 token=ad7af931-3cf6-4000-967d-925dcfc44955
Keep in mind, that this way you don’t have to specify the url and the token as lr-cli.sh parameters, so commands are much more readable. Through this article we assume that you have a lr-cli.properties file with url and authentication token specified (as it is shown above), and just occasionally provide a full version of a command with those parameters.
With the CLI script and your authentication token or username/password combination you are able to manage the following aspects of your LiveRebel Command Center.
- List known application servers
- Upload new application version
- List all managed applications
- Retrieve a list of available versions for application
- Deploy managed application to servers
- Compare application versions
- Update your running application to a new version
- Pause requests while updating and resume them manually
- List updates in process
- Resume manual update
- Undeploy an application
- Remove application from LiveRebel
- General error codes
List Known Application Servers
LiveRebel is connected with the running application servers and allows to manage applications deployed on the servers. Usually, commands that allow you do something with servers, deploy or undeploy application, or update application version, for example, accept –servers parameter. If this parameter is specified (a comma separated list of server ids) then this command applies only to those servers.
To obtain server IDs execute servers command.
> # if you don’t have lr-cli.properties file. > #./lr-cli.sh -token ad7af931-3cf6-4000-967d-925dcfc44955 -url localhost:9001 \ servers > # if you have properties file > ./lr-cli.sh servers 1c58f90162c7895ce3ceef2a04b946d1 600f6b42bdaf6117961bbad27a729ccf
Current example shows that LiveRebel knows about two servers which are identified by strings 1c58f90162c7895ce3ceef2a04b946d1 and 600f6b42bdaf6117961bbad27a729ccf. These are server IDs.
Upload new application version
The upload command will upload a new application archive to LiveRebel Command Center. This will not update your running applications but will only transfer the archive to the Command Center. You can activate this version later. In our example we are uploading RebelChat version 2.0 and version 2.2 war archives.
> # if you don’t have lr-cli.properties file. > #./lr-cli.sh -token ad7af931-3cf6-4000-967d-925dcfc44955 -url \ localhost:9001 upload -file RebelChat2.0.war > # if you have properties file > ./lr-cli.sh upload –file RebelChat2.0.war SUCCESS > ./lr-cli.sh upload –file RebelChat2.2.war SUCCESS
Mind you that that your archives might be quite large and the server far from your own machine so this process might take some time. It will depend on your upload speed. Successful upload will notify you with SUCCESS response and 0 error code. Other responses mean failure, also error code will differ from 0. As an example we try to upload version 2.0 war once again.
> ./lr-cli.sh upload -file RebelChat2.0.war FAILURE: Version 2.0 of application RebelChat already exists.
List All Managed Applications
LiveRebel manages applications that have been configured with a liverebel.xml file and they are visible from the web interface. You can access the same information from the command line. You can also find out which versions are available in the LiveRebel Command Center and also which version is the active version deployed to your cluster.
> ./lr-cli.sh apps RebelChat > ./lr-cli.sh -verbose apps Application: RebelChat Versions: 2.0, 2.2 Active: 2.0
Here you can see that there is single application RebelChat. If you want more info about which versions are uploaded to LiveRebel and which version is active, add –verbose flag to the command.
Retrieve a list of available versions for application
The same information as verbose version of apps gives you, can be retrieved in a more script-friendly way using command vers. Mandatory parameter –app specifies which application version do you want.
> ./lr-cli.sh ver –app RebelChat 2.0 2.2 > ./lr-cli.sh ver –app RebelChat -active 2.0
If you add –active flag, the result will contain only active version of the application.
Deploy managed application to servers
Now you can use deploy command to deploy previously uploaded application to your application servers. You need to specify which application and which version to deploy with –app and –ver params. Optional parameter –contextPath can be used to deploy an application with a specific context path. If it is not given, context path is derived from application name. Another optional parameter is –servers which should specify comma separated list of server ids (see servers command), to describe on which servers deploy.
> ./lr-cli.sh deploy -app RebelChat -ver 2.0 -contextPath rebel-chat \ -servers 1c58f90162c7895ce3ceef2a04b946d1,600f6b42bdaf6117961bbad27a729ccf SUCCESS
Other than SUCCESS responses or return codes that are not 0 mean that something went wrong.
Compare Application Versions
Now that you have couple of versions of your application available on the LiveRebel Command Center we can start comparing them to find out if the update is supported by LiveRebel or not. We’ll start off with a diff from 2.0 to 2.2. This update is Compatible which means that it is safe to do this update, without breaking anything.
> ./lr-cli.sh diff -app RebelChat -from 2.0 -to 2.2 Compatible > ./lr-cli.sh diff -app RebelChat -from 1.1 -to 1.3 Incompatible > ./lr-cli.sh diff -app RebelChat -from 1.0 -to 1.1 Compatible with warnings
The output of this command has 3 different states, Compatible, Compatible with warnings and Incompatible. Respective return codes are 0, 1 and 2.
Update your running application to a new version
Now that you have multiple versions of the application at LiveRebel Command Center, lets run some updates to actually update your running updates. The following command will update RebelChat from version to version 2.2. Be sure the check the compatibility beforehand.
> ./lr-cli.sh update -app RebelChat -ver 2.2 Version 1.2 activated.
Now, you can specify –timeout parameter, like –timeout 30, and LiveRebel will wait 30 seconds for all current request to finish, before proceeding with an update. If you want LiveRebel to wait before new application version is activated (after update is done), you will need –pause or –manual flags. Update command with –pause flag specified LiveRebel will wait for standard input hint to proceed. Manual mode on the other hand allows you to resume this update with completely different lr-cli call (see resume command).
Here is an example of a update command with pause and timeout parameters specified.
> ./lr-cli.sh update -app RebelChat -ver 2.2 -pause -timeout 10 The current update is paused. Press enter to finish the update! Resuming update... Version 2.2 activated.
Flag -manual, when specified, will on the other hand pause update and exit from the current lr-cli call.
> ./lr-cli.sh update -app RebelChat -ver 2.2 -manual 1
This version of update command is targeted to be used in scrips, so it responds only with ongoing update process id. If there were any problems with update, return code of lr-cli will be different from 0.
List updates in process
When you execute update command with a –manual flag, it responds with update id. To see ids of all updates that were paused and wait for a manual resume, try list-updates command:
> ./lr-cli.sh list-updates 1
It responds with a single id of an update that we started in a previous section. If there are more than one update waiting for a resume command, each update id will be on a separate line. After you get an update id, you can resume it.
Resume manual update
To resume a manual update use resume command, you will need to provide an id of the update with -id param.
> ./lr-cli.sh resume -id 1 SUCCESS
Like with any other call, if the return code is 0 it means, that everything was fine, and other values correspond to a failure of execution. Successful execution of a resume means that paused update was completed.
Undeploy an application
In the same way like you deployed an application to servers connected to Command Center, you can undeploy an application with an undeploy command. Optional parameter –servers accepts comma separated list of servers from which to undeploy the application referenced by –app parameter. If you skip –servers parameter, application will be undeployed from all servers where it is deployed.
> ./lr-cli.sh undeploy -app RebelChat -servers \ a41ec238ecfe2c79c11fc8c9e16b3a85,4ed316e71f62d603b8a8b6b9063a2060 SUCCESS
Like with any other call, if the return code is 0 it means, that everything was fine, and other values correspond to a failure of execution.
Remove application from LiveRebel
Finally, you can completely remove an application from Command Center by executing a remove command. You cannot remove an application that is deployed to at least one server. So after you have undeployed the application from all servers you can safely remove it.
>./lr-cli.sh remove -app RebelChat SUCCESS
Like with any other call, if the return code is 0 it means, that everything was fine, and other values correspond to a failure of execution.
Now we have covered how CLI helps you to manage application lifecycle with LiveRebel. Happy scripting!
Error codes
By the way, if you want to know what a specific return code of a lr-cli.sh/lr-cli.cmd means, here is a brief description of general codes.
- 9 – you have provided an invalid URL,
- 11 – access denied, invalid username or password, or token;
- 12 – unexpected server error, please write us about these at the forum or mail us.
- 13 – unable to read server response, these are also really good candidates for a bug report
- 14 – can’t connect to the server, check if you can login into Command Center or something.
- 15 – unexpected error (this time in CLI application), shame on us! But, please, don’t forget to report this.
If you encounter these or have a functionality you can’t live without, please, write us about it, we are glad to make CLI better.
