Get started with the Deploy CLI
You can use the Deploy command-line interface (CLI) to control and manage multiple features, such as discovering middleware topology, setting up environments, importing packages, and performing deployments. The CLI connects to the Deploy server using the standard HTTP/HTTPS protocol, so it can be used remotely without firewall issues.
Install the CLI
Download the Deploy CLI archive, which is in the ZIP format:
- If you have an Enterprise Edition license, download from the Deploy/Release Software Distribution site. This requires customer log-in.
- If you have a trial license, download from the trial download page.
- Create an installation directory such as
C:\Program Files\Deploy\CLI, referred to as
XL_DEPLOY_CLI_HOMEin this topic.
- Copy the Deploy CLI archive to the directory.
Extract the archive in the directory.
For more information on installation settings, see Install the Deploy CLI.
If you have configured your Deploy server to use a self-signed certificate, you must also configure the CLI to trust the server. For more information, see self-signed certificate and configure the CLI to trust the server with a self signed certificate
Connect to Deploy using the CLI
Connect to the Deploy server
- Ensure that the Deploy server is running.
Open a terminal window or command prompt and go to the
XL_DEPLOY_CLI_HOMEis the directory where the CLI is installed.
Execute the start command:
- Unix-based operating systems:
- Microsoft Windows:
- Unix-based operating systems:
- Enter your username and password.
The CLI attempts to connect to the server on
localhost, running on the Deploy standard port of
Enter the Deploy server credentials
Provide your username and password for accessing the Deploy server, using one of the following methods:
- Enter the credentials manually in the CLI.
- Provide the credentials with the
- Store the credentials in the
cli.passwordproperties in the
Special characters on the Windows command line
Characters such as
" have a special meaning in the Microsoft Windows command prompt. If you use these in your password and you pass them to the Deploy server as-is, the log in fails.
To prevent this issue, surround the password with quotation marks (
"). If the password contains a quotation mark, you must triple it. For example,
My!pass^wo"rd should be entered as
CLI startup options
When you start the CLI, the following options are available:
||Pass an alternative configuration directory to the CLI. The CLI will search for a
||If provided, the
Note: If the Deploy context root is set to
||Starts the CLI in batch mode to run the provided Python file. After the script completes, the CLI will terminate. The Deploy CLI can load and run Python script files with the maximum size of 100 KB.|
||Alternative for the
||Defines the default socket timeout in milliseconds which is the timeout for waiting for data. The default value is 10000.|
||Specifies the host the Deploy server is running on. The default host is
||Specifies the port where to connect to the Deploy server. If the port is not specified, it will use the Deploy default port
||Specifies the HTTP proxy host if Deploy must to be accessed through an HTTP proxy.|
||Specifies the HTTP proxy port if Deploy must to be accessed through an HTTP proxy.|
||Instruct the CLI to connect to the Deploy server using HTTPS. By default, it will connect to the secure port 4517, unless a different port is specified with the
||The username for logging in. If the username is not specified, the CLI will enter interactive mode and prompt the user.|
||The password for logging in. If the password is not specified, the CLI will enter interactive mode and prompt the user.|
||Suppresses the display of the welcome banner.|
||Alternative for the
||Lists the startup options.|
help option in the CLI
To access help in the CLI, execute the
help command in a terminal or command prompt.
To get information about a specific object, execute
To get information about a specific method, execute
For more information, see objects available in the Deploy CLI.
CLI startup example
The following is an example of CLI startup options:
./cli.sh -username User -password UserPassword -host xl-deploy.local
This connects the CLI as
User with password
UserPassword to the Deploy server running on the host
xl-deploy.local and listening on port
Pass arguments to CLI commands or scripts
You can pass arguments from the command line to the CLI. You are not required to specify any options to pass arguments.
Example of passing arguments without specifying options:
./cli.sh these are four arguments
Example of passing arguments with options:
./cli.sh -username User -port 8443 -secure again with four arguments
You can start an argument with the
- character. To instruct the CLI to interpret it as an argument instead of an option, use the
-- separator between the option list and the argument list:
./cli.sh -username User -- -some-argument there are six arguments -one
This separator must be used only if one or more of the arguments begin with
To pass the arguments in commands executed on the CLI or in a script passed with the
-f option, you can use the
sys.argv[index] method, where the index runs from 0 to the number of arguments. Index 0 of the array contains the name of the passed script, or is empty when the CLI was started in interactive mode. The first argument has index 1, the second argument index 2, and so forth. Using the command line in the first example presented above, the following commands:
import sys print sys.argv
['', '-some-argument', 'there', 'are', 'six', 'arguments', '-one']
Sample CLI scripts
This is an example of a CLI script that deploys the BookStore 1.0.0 application to an environment called TEST01:
# Load package package = repository.read('Applications/Sample Apps/BookStore/1.0.0') # Load environment environment = repository.read('Environments/Testing/TEST01') # Start deployment deploymentRef = deployment.prepareInitial(package.id, environment.id) depl = deployment.prepareAutoDeployeds(deploymentRef) task = deployment.createDeployTask(depl) deployit.startTaskAndWait(task.id)
This is an example of the same deployment with an :
# Load package package = repository.read('Applications/Sample Apps/BookStore/1.0.0') # Load environment environment = repository.read('Environments/Testing/TEST01') # Start deployment depl = deployment.prepareInitial(package.id, environment.id) depl2 = deployment.prepareAutoDeployeds(depl) depl2.deployedApplication.values['orchestrator'] = 'parallel-by-container' task = deployment.createDeployTask(depl2) deployit.startTaskAndWait(task.id)
For more information on objects, see types of orchestrators in Deploy
This is an example of a script that undeploys BookStore 1.0.0 from the TEST01 environment:
taskID = deployment.createUndeployTask('Environments/Testing/TEST01/BookStore').id deployit.startTaskAndWait(taskID)
Extend the CLI
You can extend the Deploy CLI by installing extensions that are loaded during CLI startup. These extensions can be Python scripts. For example, a script with Python class definitions that will be available in commands or scripts that run from the CLI. This feature can be combined with the arguments provided on the command line when starting up the CLI.
To install a CLI extension:
- Create a directory with the name
extin the directory where will start the CLI. During startup, in the current directory, Deploy will search for the existence of the
- Copy Python scripts into the
- Restart the CLI. During startup, the CLI will search for, load, and execute all scripts with the
clisuffix found in the
Note: The order in which scripts from the
ext directory are executed is not defined.
Log out of the CLI
To log out of the CLI in interactive mode, execute the
quit command in the terminal or command prompt.
In batch mode, when a script is provided, the CLI automatically terminates after finishing the script.
For more information about using the CLI, see: