> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quixa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless CLI & CI/CD Quality Gates

> Run flows and suites headlessly in Jenkins, GitHub Actions, and Azure DevOps using @quixa/cli with JUnit reporting.

Visual workflows deliver maximum value when integrated as automated verification gates within continuous integration and continuous delivery (CI/CD) pipelines.

The **Quixa Headless CLI** (`@quixa/cli`) is a lightweight, zero-dependency runner for executing flows and regression suites directly from terminal environments and build servers.

```mermaid theme={null}
flowchart LR
    Git["Git Push / PR"] --> CI["CI/CD Pipeline (GitHub / Azure DevOps / Jenkins)"]
    CI --> CLI["quixa run suite 'Regression Suite'"]
    CLI --> Gate{"Pass / Fail Exit Code (0 / 1)?"}
    Gate -- "Exit 0" --> Deploy["Proceed to Production Deployment 🚀"]
    Gate -- "Exit 1" --> Halt["Halt Pipeline & Publish JUnit XML 🛑"]
```

***

## 1. Installation

Install the CLI globally or within your project:

```bash theme={null}
npm install -g @quixa/cli
```

Authenticate using an enterprise API Key or OAuth2 Client Credentials:

```bash theme={null}
export QUIXA_BASE_URL="https://api.example.com"
export QUIXA_API_KEY="qxa_live_YOUR_KEY"
```

***

## 2. Command Reference

### Running a Flow

Execute a single flow headlessly by ID:

```bash theme={null}
quixa run flow 7b43a29b-810e-436f-b258-45091c6e61f2 --env staging
```

### Running a Flow Suite

Execute an entire regression suite with topological flow ordering:

```bash theme={null}
quixa run suite "Core Service Regression" --env staging --output junit --report-file ./test-results.xml
```

### Key CLI Flags

* `--env <name>`: Target environment (`dev`, `staging`, `prod`).
* `--output <format>`: Report format (`console`, `json`, `junit`).
* `--fail-fast`: Immediately halt suite execution upon the first failed node or assertion.
* `--timeout <ms>`: Overrides flow-level timeout limits.

***

## 3. CI/CD Integration Examples

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    name: Quixa E2E Regression Gate
    on: [push, pull_request]

    jobs:
      regression:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'

          - name: Run Quixa Suite
            env:
              QUIXA_BASE_URL: ${{ secrets.QUIXA_BASE_URL }}
              QUIXA_API_KEY: ${{ secrets.QUIXA_API_KEY }}
            run: |
              npx @quixa/cli run suite "Nightly Regression" --env staging --output junit --report-file results.xml

          - name: Publish Test Report
            uses: mikepenz/action-junit-report@v4
            if: always()
            with:
              report_paths: 'results.xml'
    ```
  </Tab>

  <Tab title="Azure DevOps">
    ```yaml theme={null}
    steps:
      - task: Npm@1
        inputs:
          command: 'custom'
          customCommand: 'install -g @quixa/cli'

      - script: |
          quixa run suite "Nightly Regression" --env staging --output junit --report-file $(Build.SourcesDirectory)/quixa-results.xml
        displayName: 'Execute Quixa Regression Suite'
        env:
          QUIXA_BASE_URL: $(QuixaBaseUrl)
          QUIXA_API_KEY: $(QuixaApiKey)

      - task: PublishTestResults@2
        condition: always()
        inputs:
          testResultsFormat: 'JUnit'
          testResultsFiles: '$(Build.SourcesDirectory)/quixa-results.xml'
    ```
  </Tab>
</Tabs>

***

## 4. Dynamic Test Data Feeding for Playwright, Cypress & Selenium

Beyond acting as standalone test suites, Quixa flows can be invoked programmatically from existing UI test frameworks to provision complex, stateful test data on-demand:

```typescript theme={null}
// Inside a Playwright or Cypress test hook
test.beforeEach(async () => {
  // Trigger a Quixa flow to provision a fresh, verified customer
  const response = await fetch('https://api.example.com/api/v1/flows/provision-user/execute', {
    method: 'POST',
    headers: { 'X-API-Key': process.env.QUIXA_API_KEY }
  });
  
  const { customerId, initialToken } = await response.json();
  
  // Proceed with browser test using guaranteed clean, collision-free data
  await page.goto(`https://app.example.com/login?token=${initialToken}`);
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.