XL Command Line Interface reference

The xl command line tool provides a fast and straightforward method for provisioning Digital.ai Release, Deploy, and Runner servers using YAML files. The YAML files can include items such as releases, pipelines, applications, infrastructure, and target environments. In addition, the XL CLI is used for installing or upgrading Digital.ai Deploy and Release.

Usage

xl [command]

Available Commands

Command	Description
apply	Apply configuration changes
blueprint	Create a Blueprint
generate	Generate configuration
help	Help about any command
ide	IDE commands
license	Display license info
kube	Install, upgrade, or clean Digital.ai Deploy or Release using Operator.
preview	Preview Deployment
version	Display version info
wrapper	Generate XL wrapper

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 xl
-q, --quiet	suppress all output, except for errors
-v, --verbose	verbose output
--xl-deploy-authmethod string	Authentication method to access the Digital.ai Deploy server, possible values are http, login (default "http")
--xl-deploy-password string	Password to access the Digital.ai Deploy server (default "admin")
--xl-deploy-token string	Personal access token to access the Digital.ai Deploy server
--xl-deploy-url string	URL to access the Digital.ai Deploy server (default http://localhost:4516/)
--xl-deploy-username string	Username to access the Digital.ai Deploy server (default "admin")
--xl-release-authmethod string	Authentication method to access the Digital.ai Release server, possible values are http, login, token (default "http")
--xl-release-password string	Password to access the Digital.ai Release server (default "admin")
--xl-release-token string	Personal access token to access the Digital.ai Release server
--xl-release-url string	URL to access the Digital.ai Release server (default http://localhost:5516/)
--xl-release-username string	Username to access the Digital.ai Release server (default "admin")

note

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

Authenticate Using a Personal Access Token (PAT)

You can authenticate with a personal access token (PAT) by specifying the authentication method as token and passing the token value with the appropriate flag.

For Deploy:

xl.exe generate xl-deploy --xl-deploy-authmethod token --xl-deploy-token <TOKEN> -p Applications -f Applications.yaml

For Release:

xl.exe generate xl-release --xl-release-authmethod token --xl-release-token <TOKEN> -p Applications -f Applications.yaml

These commands use the pregenerated token to connect to the respective server and export the list of applications into the specified YAML file.

Authenticate Using a Config File

You can store authentication credentials and server configuration in a YAML config file to avoid passing parameters with each command. Create a config file with your authentication details:

Example config.yaml:

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

Using the config file:

xl.exe --config config.yaml generate xl-deploy -p Applications -f Applications.yaml
xl.exe --config config.yaml generate xl-release -p Applications -f Applications.yaml

This approach reads authentication settings from the config file, simplifying command execution and keeping tokens secure.

note

Command-line authentication flags will override config file settings when both are provided.

xl apply Command

Use the xl apply command to execute YAML specifications.

note

If you try to overwrite the YAML specification file after deployment,you will receive an error message "Error while processing YAML document at line 1 of XL YAML file E:\demo\applications.yaml: Unexpected response: File cannot be updated. If you want to change the file, create a new CI for the artifact" and you cannot override the file specification.

Syntax

xl apply [flag] [value]

Command-specific flags

Flag	Description
-d, --detach	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 one 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

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.

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

Use the xl generate command to generate a YAML file for existing configurations in Deploy or 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 Release and Work with the YAML format for Deploy 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 Deploy, the generate operation is limited to 256 configuration items (CIs).
• For Release, a reasonable limit (currently 32) to the number of templates you can generate is enforced.

Syntax

xl generate [product] [flag] [value]

Assistance with commands

The following flags will provide you with the available commands:

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

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

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.
--deliveryPatterns	Adds all the delivery patterns to the generated file.
-e, --environments	Adds all the system environments and environment reservations 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. **Example**: ./xl generate xl-release --templates -f templates.yml -o --name "*template_test_0?
-o, --override	Set to true to overwrite an existing YAML file with the same name in the target directory.
-p, --path string	Server folder path which will be used for definitions generation. Leave empty to generate all global and folder entities. Use / to generate exclusively global entities.
-m, --permissions	Adds all the permissions in the system including the task permissions 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.xlvals 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. The user passwords are not stored in the secrets.xlvals file when you use the -u flag.
-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 generate will export only internal users because those are the only user types you can import.
--settings	Adds all the general settings to the generated file.
--notifications	Adds all the email notification settings to the generated file.
-b, --variables	Adds all the variables in system to the generated file.
--calendar	Adds all the blackout and special days from calendar to the generated file.
--defaults	Include properties that have default values. 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.
--triggers	Adds all triggers in the system to the generated file.

Deploy generate-specific flags

Flag	Description
-d, --defaults	Include properties that have default values. (Only works for 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.xlvals 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. The user passwords are not stored in the secrets.xlvals file when you use the -u flag.
-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 Digital.ai Deploy server, possible values are http, login (default "http")
--xl-deploy-password string	Password to access the Digital.ai Deploy server (default "admin")
--xl-deploy-token string	Personal access token to access the Digital.ai Deploy server
--xl-deploy-url string	URL to access the Digital.ai Deploy server (default http://localhost:4516/)
--xl-deploy-username string	Username to access the Digital.ai Deploy server (default "admin")
--xl-release-authmethod string	Authentication method to access the Digital.ai Release server, possible values are http, login, token (default "http")
--xl-release-password string	Password to access the Digital.ai Release server (default "admin")
--xl-release-token string	Personal access token to access the Digital.ai Release server
--xl-release-url string	URL to access the Digital.ai Release server (default http://localhost:5516/)
--xl-release-username string	Username to access the Digital.ai Release server (default "admin")

Examples

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

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 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

Export Configuration Items With xl generate

The xl generate command is used to export Configuration Items (CIs) from Deploy into YAML file. The output of the xl generate command depends on the combination of permissions assigned. Below table shows the export behavior for both admin and non-admin users:

Admin Users

Permissions Assigned	Export Result
Admin	CI details only + folder permission details including global roles and users

Non-Admin Users

Permissions Assigned	Export Result
No permissions	Export fails with authorization error
Security Edit/View permission	CI details + folder permission details including global roles and users
Folder read permission only	CI details only

Example

xl generate xl-deploy -p Infrastructure/my-folder -f export.yaml

Depending on your permissions, the xl generate command exports both CI content and folder permissions.

xl license Command

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

Example

xl license

xl preview Command

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.
• StitchPreview kind: Preview the stitch transformations by running the xl apply command.

In all 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 [])

Example

xl preview -f deploy-myapp.yaml

xl version Command

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

Example

xl version

xl wrapper Command

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.

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 Digital.ai Deploy server, possible values are http, login (default "http")
--xl-deploy-password string	Password to access the Digital.ai Deploy server (default "admin")
--xl-deploy-token string	Personal access token to access the Digital.ai Deploy server
--xl-deploy-url string	URL to access the Digital.ai Deploy server (default http://localhost:4516/)
--xl-deploy-username string	Username to access the Digital.ai Deploy server (default "admin")
--xl-release-authmethod string	Authentication method to access the Digital.ai Release server, possible values are http, login, token (default "http")
--xl-release-password string	Password to access the Digital.ai Release server (default "admin")
--xl-release-token string	Personal access token to access the Digital.ai Release server
--xl-release-url string	URL to access the Digital.ai Release server (default http://localhost:5516/)
--xl-release-username string	Username to access the Digital.ai Release server (default "admin")

xl kube Command

See xl kube Command Reference.

xl plugin Command

See xl plugin deploy Command Reference.