Install the XL CLI

This topic describes the system requirements, installation, and syntax for the XL Command Line Interface (XL CLI) used to support Digital.ai DevOps as Code and blueprints features.

System requirements

Use the version of the XL CLI that corresponds to the version of Deploy or Release you are using. The XL CLI works with the following Digital.ai products:

• Deploy
• Release

You can install the XL CLI on supported 64-bit versions of the following operating systems:

• Linux
• macOS
• Windows

Install the XL CLI

You can install the XL CLI on any computer that can access the XebiaLabs servers in your environment.

Install the XL CLI on Linux

From the computer on which you want to install the XL CLI, open a terminal and run the following commands:

$ curl -LO https://dist.xebialabs.com/public/xl-cli/$VERSION/linux-amd64/xl
$ chmod +x xl
$ sudo mv xl /usr/local/bin

Notes:

• For $VERSION, navigate to the public folder to view available versions and substitute the desired version that matches your product version. The CLI version will also control the list of blueprints you can view.
• The /usr/local/bin location is an example. You can place the file in a preferred location on your system.

Install the XL CLI on macOS

From the computer on which you want to install the XL CLI, open a terminal and run the following commands:

$ curl -LO https://dist.xebialabs.com/public/xl-cli/$VERSION/darwin-amd64/xl
$ chmod +x xl
$ sudo mv xl /usr/local/bin

Notes:

• For $VERSION, navigate to the public folder to view available versions and substitute the desired version.
• The /usr/local/bin location is an example. You can place the file in a preferred location on your system

Install the XL CLI on Windows

From the computer on which you want to install the XL CLI, do the following:

1. Download the XL CLI executable file from the following location:

https://dist.xebialabs.com/public/xl-cli/$VERSION/windows-amd64/xl.exe

Note: For $VERSION, navigate to the public folder to view available versions and substitute the desired version.

2. Place the file in a preferred location on your system (for example, C:\Program Files\XL CLI).

Set environment variables

Set environment variables so that you can run the standalone executable for the XL CLI from a command line without specifying the path in which the executable is located:

• For macOS or Linux, you can place the XL CLI executable in your usr/local/bin location. You can also modify your path to include another directory in which the executable is stored.

• For Windows, add the root location where you placed the XL CLI executable to your system Path variable.

Manage the XL CLI config file

When you initially run the XL CLI, and assuming no configuration file exists, a default configuration file named config.yaml is dynamically created in the .xebialabs folder located in your home directory (default: $HOME/.xebialabs/config.yaml).

The XL CLI configuration file (config.yaml) includes:

• XebiaLabs server URLs and associated credentials
• Details about your blueprint repositories

Note The config.yaml file contains secret values and you should carefully manage the users who can access it.

Customize this file to suit your environment. By maintaining these details in a separate file, you can avoid having to explicitly specify this information in XL CLI commands.

config.yaml format

Here is the default CLI configuration file content:

blueprint:
  current-repository: XL Blueprints
  repositories:
  - name: XL Blueprints
    type: http
    url: https://dist.xebialabs.com/public/blueprints/${CLIVersion}/
xl-deploy:
  authmethod: http
  password: admin
  url: http://localhost:4516/
  username: admin
xl-release:
  authmethod: http
  password: admin
  url: http://localhost:5516/
  username: admin

You can define multiple blueprint repositories (GitHub and/or HTML) by adding them to the blueprints: section. In the example that follows, two blueprint repositories are defined:

Repo name	Type	Description
XL Blueprints	HTTP	HTTP blueprint location. Reads index.json file in this location for blueprint list
my-github	GitHub	GitHub blueprint location. In this example, this is the default repository (current-repository)

Multiple repository example:

blueprint:
  current-repository: my-github
  repositories:
  - name: XL Blueprints
    type: http
    url: https://dist.xebialabs.com/public/blueprints/
  - name: my-github
    type: github
    repo-name: blueprints
    owner: mycompany
    branch: development
    token: GITHUB_TOKEN

Use a wrapper script

By default, you have a single configuration file to manage details for your default Deploy, Release, and blueprint template repositories. If you need to connect to different Deploy or Release servers in your environment, you can create and use multiple configuration files. You can then explicitly specify which file to use when executing XL CLI commands using the --config string global flag; for example, --config /path/to/conf.yaml.

DevOps as Code is designed to work with any continuous integration tool that can run commands. By using specifications defined in the DevOps as Code YAML format and a simple XL CLI utility to execute them, DevOps as Code offers a lightweight but powerful integration for deploying your applications using common continuous integration tools.

To simplify your integration, you can utilize a wrapper script to bootstrap the XL CLI commands on your Unix or Windows-based continuous integration servers without having to install the XL CLI executable itself. The script is stored with your project YAML files and you can execute XL CLI commands from within your continuous integration tool scripts.

Wrapper advantages

The DevOps as Code functionality and the use of a wrapper with your continuous integration tool will enable you to automatically fetch a specific version of the XL CLI binary file. You can:

• Store YAML files in source control.
• Create configuration items (CIs) in Deploy and start a release in Release with a single command.
• Eliminate the need to install a Digital.ai plugin in your continuous integration tool.

Add a wrapper script to your project

To add a wrapper script to your project, execute the xl wrapper command from the project root and then continue to develop the YAML files for your project. When you store project files in your source code repository, the wrapper script will be included and can then be invoked within your continuous integration tool.

The following sections provide examples of how to utilize this configuration in common continuous integration tools (Jenkins, Travis CI, and Microsoft Azure DevOps).

Jenkins

To execute XL CLI commands from within your Jenkinsfile:

1. Depending on your continuous integration server OS, define a sh (Linux or macOS) or bat (Windows) step in your Jenkinsfile.

   For Windows:

     ....
     stages {
         stage("Apply xebialabs.yaml") {
             steps {
                 bat "xlw.bat apply -v -f xebialabs.yaml"
             }
         }
     }
   

   For Linux/macOS:

     ....
     stages {
         stage("Apply xebialabs.yaml") {
             steps {
                 sh "./xlw apply -v -f xebialabs.yaml"
             }
         }
     }

2. When the steps defined in the Jenkinsfile are executed, the XL CLI commands also will be executed using your YAML file(s).

3. You can configure additional bat or sh calls by adding desired XL CLI commands and parameters.

Travis CI

To execute XL CLI commands from within your .travis.yml file:

1. Define a script step in your .travis.yml file. For example:

   ./xlw apply -f xebialabs.yml

2. When the steps defined in the .travis.yml file are executed, the XL CLI commands also will be executed using your YAML file(s).

3. You can configure additional script calls by adding desired XL CLI commands and parameters.

Microsoft Azure DevOps

On Microsoft Azure DevOps you can define your build pipeline using a YAML file which is typically called azure-pipeline.yml and located in the root of the repository.

To execute XL CLI commands from within your azure-pipeline.yml file:

1. Depending on your continuous integration server OS, define a sh (Linux or macOS) or bat (Windows) step in your azure-pipeline.yml file.

   For Windows:

   os: windows
   script:
     - cmd.exe /c "xlw.bat apply -f xebialabs.yaml"

   For Linux/macOS:

   os: linux
   script:
   - ./xlw apply -f xebialabs.yaml

2. When the steps defined in the azure-pipeline.yml file are executed, the XL CLI commands also will be executed using your YAML file(s).

3. You can configure additional bat or sh calls by adding desired XL CLI commands and parameters.