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

1. 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.
2. Create an installation directory such as /opt/xebialabs/xl-deploy-cli or C:\Program Files\Deploy\CLI, referred to as XL_DEPLOY_CLI_HOME in this topic.
3. Copy the Deploy CLI archive to the directory.
4. 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

1. Ensure that the Deploy server is running.

2. Open a terminal window or command prompt and go to the XL_DEPLOY_CLI_HOME/bin directory.

   Note: The XL_DEPLOY_CLI_HOME is the directory where the CLI is installed.

3. Execute the start command:

   • Unix-based operating systems: ./cli.sh
   • Microsoft Windows: cli.cmd

4. Enter your username and password. The CLI attempts to connect to the server on localhost, running on the Deploy standard port of 4516.

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 -username and -password options.
• Store the credentials in the cli.username and cli.password properties in the XL_DEPLOY_CLI_HOME/conf/deployit.conf file.

Special characters on the Windows command line

Characters such as !, ^, or " 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 -password "My!pass^wo"""rd".

CLI startup options

When you start the CLI, the following options are available:

Option	Description
-configuration config_directory	Pass an alternative configuration directory to the CLI. The CLI will search for a deployit.conf in this location. The configuration file supports the cli.username and cli.password options.
-context newcontext	If provided, the context value will be added to the Deploy server connection URL. For example, if newcontext is specified, the CLI will attempt to connect to the Deploy server REST API at http://host:port/newcontext/deployit. The leading slash and REST API endpoint (deployit) will automatically be added if they are omitted from the parameter. Note: If the Deploy context root is set to deployit, the -context value must be /deployit/deployit.
-f Python_script_file	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.
-source Python_script_file	Alternative for the -f option.
-socketTimeout timeout_value	Defines the default socket timeout in milliseconds which is the timeout for waiting for data. The default value is 10000.
-host myhost.domain.com	Specifies the host the Deploy server is running on. The default host is 127.0.0.1 (localhost).
-port 1234	Specifies the port where to connect to the Deploy server. If the port is not specified, it will use the Deploy default port 4516.
-proxyHost VAL	Specifies the HTTP proxy host if Deploy must to be accessed through an HTTP proxy.
-proxyPort N	Specifies the HTTP proxy port if Deploy must to be accessed through an HTTP proxy.
-secure	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 -port option. To connect, the Deploy server must have been started using this secured port. This is enabled by default.
-username myusername	The username for logging in. If the username is not specified, the CLI will enter interactive mode and prompt the user.
-password mypassword	The password for logging in. If the password is not specified, the CLI will enter interactive mode and prompt the user.
-q	Suppresses the display of the welcome banner.
-quiet	Alternative for the -q option.
-h	Lists the startup options.

Use the 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 <objectname>.help(). To get information about a specific method, execute <objectname>.help("<methodname>"). 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 4516.

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

Generated output:

['', '-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:

1. Create a directory with the name ext in the directory where will start the CLI. During startup, in the current directory, Deploy will search for the existence of the ext directory.
2. Copy Python scripts into the ext directory.
3. Restart the CLI. During startup, the CLI will search for, load, and execute all scripts with the py or cli suffix found in the ext directory.

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.

Related topics

For more information about using the CLI, see:

• Objects available in the Deploy CLI
• Types used in the Deploy CLI
• Set up roles and permissions using the using the CLI
• Working with configuration items in the CLI
• Execute tasks from the Deploy CLI
• Export items from or import items into the repository