@digital-ai/plugin-scaffolder-backend-module-digitalai-xlcli/README.md

xlcli custom action for @backstage/plugin-scaffolder-backend

# @digital-ai/plugin-scaffolder-backend-module-digitalai-xlcli
# 🚀 Digital.ai XL CLI Apply Actions

This Backstage software template actions enables applying configuration files to 
**Digital.ai XL Deploy** or **XL Release** using the `xl apply` command via the **XL CLI**.

---

## 🧩 What It Does

Based on user input, the template:

- Determines whether to use **XL Deploy** or **XL Release**
- Applies the specified configuration YAML file using the `xl` CLI
- Uses credentials and host information from backstage app-config.yaml
- Outputs the target environment URL after command success. 

---

## ⚙️ How It Works

This template uses a custom Backstage scaffolder action called `xlcli:apply`. The action:

1. Locates the `xl` CLI binary
2. Reads configuration values (host, username, password) using `readValues`
3. Constructs the `xl apply` command dynamically
4. Executes it and reports the result via Backstage scaffolder outputs

---

## 📝 Input Parameters

| Name       | Description                                           | Required |
|------------|-------------------------------------------------------|----------|
| `product`  | Target product: `xl-deploy` or `xl-release`           | ✅ Yes   |
| `filePath` | Path to the configuration YAML file to be applied     | ✅ Yes   |

## Installation

From your Backstage instance root folder:
```shell
yarn add --cwd packages/backend @digital-ai/plugin-scaffolder-backend-module-digitalai-xlcli
```

This will download the right `xl` cli binary for the current operating system and architecture from the dist at https://dist.xebialabs.com/public/xl-cli/

This behavior can be customized by adding a new `"xlcli"` field in your `packages/backend/package.json` file, like so:

```json
//packages/backend/package.json
{
  "xlcli": {   
    "version": "24.3.4",
    "skipDownload": false
  }
}
```
The custom actions used in this template require the xl CLI binary to function correctly.

If you choose to skip automatic downloading (using the xl.skipDownload option), make sure to satisfy one of the following conditions:

a. The path to the xl binary is explicitly configured in your app-config.yaml. (See configuration details below)
```yaml
xlcli:
# When adding this plugin to your Backstage instance, it will automatically try to download the latest xl-cli binary and use it.
# But if you already have xl cli installed, you can override the path below.
  binaryPath: '/home/ishwarya/backstage/xl_test'
```
b. The xl CLI is already installed and available in the system’s global PATH on the machine running Backstage.

## Configuration
1. Import the actions into your `packages/backend/src/index.ts` Backend Plugin of your Backstage instance: 
```ts
// packages/backend/src/index.ts
import scaffolderxlcliModule from "@digital-ai/plugin-scaffolder-backend-module-digitalai-xlcli";
const backend = createBackend();
// ....
backend.add(scaffolderxlcliModule);
```
## Preview
![Preview the xl-cli apply action in backstage.](img/previewxlcliapply.png)

## Usage
  Please refer the template [xl-cli-github](templates/xl-cli-github/README.md) and [xl-cli-yaml-inline](templates/xl-cli-yaml-inline/README.md)  for more details on how to use the xlcli apply action in the backstage template.

```yaml

    - id: xlcliApply
      name: Apply xl-cli
      action: digitalai:xlcli:apply
      input:
        product: ${{ parameters.product }}
        releaseInstance: ${{ parameters.releaseInstance }}
        filePath: ${{ parameters.filePath }}

```