XL Command Line Interface reference

This topic describes syntax and examples for the XL Command Line Interface (XL CLI). To display the XL CLI help output, type the following from your command line:

xl help

Commands

General usage: xl [command] [flag] [parameters]

Available commands: apply blueprint generate help ide license preview version wrapper

Command details

For each XL CLI command, this section describes the command syntax, command-specific flags, important details and some examples.

Tip: Type xl help for a list of global flags that can also be applied when issuing commands. Also, see Global flags for a list of flags, descriptions and default values.

xl apply command details

Use the xl apply command to execute YAML specifications.

Syntax

xl apply [flag] [value]

Command-specific flags

Flag Description
-d, --file stringarray Detach the client at the moment of starting a deployment or release
-f, --file stringarray Required. Path(s) to the file(s) to apply
-h, --help Help for the apply command
-s, --include-scm-info Send source control information. Fails if source control information cannot be found or is dirty.
For more information, see Source control management in YAML
-non-interactive Automatically archive finished deployment tasks
-p, --proceed-when-dirty Proceed with applying changes even if repository is dirty
This is used together with the s, --include-scm-info flag. For more information, see Proceed-when-dirty flag
--values stringToString Values (default [])

File order processing

You must choose at least on YAML file to perform an apply operation, but if you want to execute two or more YAML files, you can use one of the following methods:

Import kind YAML : The preferred method is to use a separate YAML file of the kind “Import” and list the YAML files to apply in order.

For example, you can create a YAML file called import-yamls.yaml

apiVersion: xl/v1
kind: Import
metadata:
  imports:
    - infra.yaml
    - env.yaml
    - app.yaml
    - xlr-pipeline.yaml

Using this method, you can then simply run the xl apply -f /tmp/import-yamls.yaml file which will in turn sequentially run the YAML files listed in the imports: section.

String multiple files in the CLI: You can also specify multiple YAML files to apply in order when running the xl apply command. For example:

xl apply -f /tmp/infra.yaml -f /tmp/env.yaml -f /tmp/app.yaml -f xlr-pipeline.yaml

Examples

xl apply -f /tmp/infra.yaml
xl apply -f /tmp/infra.yaml -f /tmp/env.yaml -f /tmp/app.yaml -f /tmp/xlr-pipeline.yaml
xl apply -f xebialabs.yaml -d

xl blueprint command details

You can use the xl blueprint command to run blueprints.

Syntax

xl blueprint [flag] [parameter]

Global Flags

  • -blueprint-current-repository: can be used to override the current-repository field of the blueprint configuration. See About Blueprint repositories for more information.

Command-specific flags

Option (short) Option (long) Default value Examples Description
-h --help - xl blueprint -h Displays the help text for the blueprint command
-a --answers - xl blueprint -a /path/to/answers.yaml When provided, values within the answers file will be used as parameter inputs. By default strict mode is off so any value that is not provided in the file will be asked to the user.
For more information, see Blueprint answers file.
-s --strict-answers false xl blueprint -sa /path/to/answers.yaml If the strict flag is set, all parameters will be requested from the answers file and errors will be shown if one of them is not there.
If it is not set, existing answer values will be used from the answers file, and the remaining ones will be asked to the user.
-b --blueprint - xl blueprint -b aws/monolith Looks for the path relative to the current repository, and instead of asking the user which blueprint to use, it will directly fetch the specified blueprint from the repository, or give an error if the blueprint is not found in the repository.
-l --local-repo - xl blueprint -l ./templates/test -b my-blueprint Local repository to use, bypassing the active repository. Can be used along with the -b flag to execute blueprints from your local filesystem without defining a repository for it.
-d --use-defaults - xl blueprint -d If the flag is set, default fields in parameter definitions will be used as value fields. Thus the user will not be asked questions for a parameter if a default value is present.

Examples

The examples shown depend on the version of XL CLI you are using.

Examples
xl blueprint --blueprint-current-repository my-github -b path/to/remote/blueprint
xl blueprint -b /path/to/local/blueprint/dir
xl blueprint -b ../relative/path/to/local/blueprint/dir

Note: For the first example, my-github must be listed in the XL CLI config file.

About Blueprint repositories

You have flexible options and considerations when managing one or more blueprint repositories. Your options depend on the version of the XL CLI you are using. See Managing blueprint repositories for more information.

xl generate command details

Use the xl generate command to generate a YAML file for existing configurations in XL Deploy or XL Release. You can use the generated specifications to extend or build your own specifications that can be executed directly using the XL CLI using the xl apply command.

See Work with the YAML format for details on YAML file root fields, kind fields and spec section options.

Note that when using xl generate, there are two sub-commands for xl-deploy and xl-release. For example, if you want to generate xl-release configurations and templates inside a folder, you can use the following command:

xl generate xl-release --templates --configurations -p your/path/to/your/folder -f filename.yml

Important: There are limitations to the number of objects you can generate:

  • For XL Deploy, the generate operation is limited to 256 configuration items (CIs).
  • For XL Release, a reasonable limit (currently 32) to the number of templates you can generate is enforced.

To bypass this limitation, set a ci-limit value in the xl-deploy.conf or xl-release.conf files as follows: XL Deploy:

xl.deploy.devops-as-code {
 ci-limit = 260
}

XL Release:

xl.devops-as-code {
 ci-limit = 35
}

Because this value can have a severe impact on your system, it is recommended to test any limit increases incrementally under load before committing to them.

Syntax

xl generate [product] [flag] [value]

Assistance with commands

The following flags will provide you with the available commands:

  • xl-deploy - xl-deploy configuration generator
  • xl-release - xl-release configuration generator

Use xl generate [command] --help for more information about a command.

XL Release generate-specific flags

Flag Description
-a, --applications Adds all the system applications to the generated file.
-c, --configurations Adds all the configurations to the generated file.
-d, --dashboards Adds all the dashboards to the generated file.
-e, --environments Adds all the system environments to the generated file.
-f, --file string Required. Path and filename where the generated YAML file will be stored.
-h, --help Help for the generate command.
-n, --name string Server entity name which will be used for definitions generation.
-o, --override Set to true to overwrite an existing YAML file with the same name in the target directory.
-p, --path string Required. Server path which will be generated.
-m, --permissions Adds all the permissions in the system to the generated file.
-k, --riskProfiles Adds all the profiles in the system to the generated file.
-r, --roles Adds all the system’s roles to the generated file.
-s, --secrets Generates a file secrets.xvals that contains all the passwords and other secret values in the system. Note: This requires admin permissions. For more information see Manage values in DevOps as Code.
-t, -templates Adds all the system’s templates to the generated file.
-u, --users Adds all the users in the system to the generated file.

XL Deploy generate-specific flags

Flag Description
-d, --defaults Include properties that have default values. (Only works for XL Deploy). This can be helpful if you are going to use the generated values on another system that may have different default values.
The --defaults flag will include default properties with empty values.
-f, --file string Required. Path and filename where the generated YAML file will be stored.
-g, --globalPermissions Adds all the system’s global permissions to the generated file .
-h, --help Help for the generate command.
-o, --override Set to true to overwrite an existing YAML file with the same name in the target directory.
-p, --path string Required. Server path which will be generated.
-r, --roles Adds all the system’s roles to the generated file.
-s, --secrets Generates a file secrets.xvals that contains all the passwords and other secret values in the system. Note: This requires admin permissions. For more information see Manage values in DevOps as Code.
-u, --users Adds all the users in the system to the generated file.

Global flags

Flag Description
--blueprint-current-repository string Current active blueprint repository name
--config string Config file (default: $HOME/.xebialabs/config.yaml)
-q --quiet Suppress all output, except for errors
-v --verbose Verbose output
--xl-deploy-authmethod string Authentication method to access the XL Deploy server (default “http”)
--xl-deploy-password string Password to access the XL Deploy server (default “admin”)
--xl-deploy-url string URL to access the XL Deploy server (default ”http://localhost:4516/”)
--xl-deploy-username string Username to access the XL Deploy server (default “admin”)
--xl-release-authmethod string Authentication method to access the XL Release server (default “http”)
--xl-release-password string Password to access the XL Release server (default “admin”)
--xl-release-url string URL to access the XL Release server (default ”http://localhost:5516/”)
--xl-release-username string Username to access the XL Release server (default “admin”)

Examples

XL Deploy examples
xl generate xl-deploy -p Applications --defaults -f /tmp/applications.yaml
xl generate xl-deploy -p Applications/PetPortal/1.0 -f applications.yaml
xl generate xl-deploy -p Environments -f /tmp/env.yaml
xl generate xl-deploy -p Infrastructure -f /tmp/infra.yaml
xl generate xl-deploy -p Configuration -f /tmp/config.yaml
XL Release examples
xl generate xl-release -p Templates/MyTemplate -f template.yaml
xl generate xl-release -p Templates/MyTemplate -f /tmp/template.yaml

Important:

When generating XL Release items with -p that have / in the template or folder name, the / character will be interpreted as a directory path. For example to export a folder with a parent folder XL and the name Release1/Release2: xl generate xl-release -p "XL/Release1/Release2" -f exports.yml This will create an error on generating: Unexpected response: Folder with path [XL/Release1] was not found To avoid this issue, escape all slashes in template or folder names with \. Note that this should not include actual path separators in the name. For example: xl generate xl-release -p "XL/Release1\/Release2" -f exports.yml

If a template or folder with / in the name is included within a generated YAML file, the characters will automatically be escaped in the template body. For example:

---
apiVersion: xl-release/v1
kind: Templates
spec:
- directory: test\/xx\/zz
  children:
 - template: qq\/ww

xl license command details

You can display license information for the open source software used in the XL CLI using the xl license command.

Command-specific flags

Flag Description
-h, --help Help for the version command

Examples

xl license

xl preview command details

You can use the xl preview command with YAML files of the following kind:

  • Deployment kind: Preview the deployment plan by running the xl apply command.
  • Release kind: Preview the release phases and tasks by running the xl apply command.

In both cases, the xl preview command will not execute any actions. It will simply provide output that details the actions the xl apply command will take, enabling you to inspect the actions and make adjustments to the YAML if needed before applying.

Command-specific flags

Flag Description
-f, --file stringarray Required. Path(s) to the file(s) to preview
-h, --help Help for the preview command
--values stringToString Values (default [])

Examples

xl preview -f deploy-myapp.yaml

xl version command details

You can display version information for the XL CLI using the xl version command.

Command-specific flags

Flag Description
-h, --help Help for the version command

Examples

xl version

xl wrapper command details

You can use the xl wrapper command to generate wrapper scripts to bootstrap the XL CLI commands on your Continuous Integration (CI) servers without having to install the XL CLI executable itself. See Use a wrapper script for details.

Syntax

xl wrapper

Flags

Flag Description
-h, --help Help for the wrapper command

Examples

xl wrapper
xl wrapper -v

Global flags

You can use global flags within all XL CLI commands to pass config file detail, credentials, and server URLs. You can also use global flags to control verbosity of the output.

The available global flags depend on the XL CLI version you are using.

Global flags

Flag Description
--blueprint-current-repository string Current active blueprint repository name
--config string Config file (default $HOME/.xebialabs/config.yaml)
-h, --help Help for the XL CLI
-q, --quiet Suppress all output, except for errors
-v, --verbose Provide verbose output
--xl-deploy-authmethod string Authentication method to access the XL Deploy server (default http)
--xl-deploy-password string Password to access the XL Deploy server (default admin)
--xl-deploy-url string URL to access the XL Deploy server. Default: http://localhost:4516/
--xl-deploy-username string Username to access the XL Deploy server (default admin)
--xl-release-authmethod string Authentication method to access the XL Release server (default http)
--xl-release-password string Password to access the XL Release server (default admin)
--xl-release-url string URL to access the XL Release server (default: http://localhost:5516/)
--xl-release-username string Username to access the XL Release server (default admin)