> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md).

# CLI Reference

Use this reference for exact CLI syntax, flags, examples, and execution order. Use [Installation and first run](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/installation.md) for the fastest working flow.

### What most teams run

{% stepper %}
{% step %}

### Tag source changes

Run a `US_SRC_*` script unless SeaLights auto-tagging is enabled.
{% endstep %}

{% step %}

### Generate report data

Run `US1_RPT_create_report_info_files.py`.
{% endstep %}

{% step %}

### Build local HTML output

Run `US2_RPT_*` when you need local report pages.
{% endstep %}

{% step %}

### Publish analytics

Run `US3_RPT_*` or `US4_RPT_*` when you need Confluence, Jira, or Azure DevOps output.
{% endstep %}
{% endstepper %}

<details>

<summary>Shared CLI patterns and exit codes</summary>

#### Multiple settings files

Most scripts support repeated `--settings` flags:

```bash
python3 <script>.py \
  --settings base_settings \
  --settings env_specific \
  --settings credentials
```

Use this when you want shared defaults, environment overrides, and separate secrets.

For merge rules, use [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md).

#### Environment variables

All settings can be overridden with environment variables:

```bash
export SEALIGHTS_API_TOKEN="your-token"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
python3 <script>.py --settings settings
```

Use this when you want CI-safe secret injection.

#### Debug logging

Run commands with debug logging when output looks wrong:

```bash
python3 <script>.py --settings settings --log-level DEBUG 2>&1 | tee debug.log
```

#### Exit codes

* `0` — success
* `1` — error. Check the logs.

Use [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) when a command fails and [Deployment patterns](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md) for end-to-end workflows.

</details>

### Environment variables

Use environment variables to inject secrets and override settings without editing files. Environment variables always override values from `settings` files.

{% hint style="info" %}
Use [Installation and first run](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/installation.md) for the fastest working setup. Use [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) for the full settings model.
{% endhint %}

#### How overrides work

The scripts load your `settings` files first.

Then they apply matching environment variables.

Use this when you want to:

* keep secrets out of source control
* vary values by environment
* override one value without copying full config files

#### Common pattern

Set variables before you run the script:

{% stepper %}
{% step %}

### Export the variables you want to override

```bash
export SEALIGHTS_API_TOKEN="your-token-here"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
```

{% endstep %}

{% step %}

### Run the target script

```bash
python3 <script>.py --settings settings
```

{% endstep %}
{% endstepper %}

#### Platform-specific overrides

Use these tabs when the override set changes by ticket platform.

{% tabs %}
{% tab title="Jira" %}
Use this when you are using Jira.

#### ✅ Prerequisites

* Your `settings` file already works for the shared settings.
* You know the Jira base URL and authorization value.
* Your JQL already returns the target issues.

#### 🚀 Steps

{% stepper %}
{% step %}

### Export the Jira query and connection values

```bash
export JIRA_AUTHORIZATION="Basic base64-encoded-credentials"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_GET_LIST_JQL="project = MYPROJ AND created >= -30d"
export JIRA_API_VERSION="3"
```

{% endstep %}

{% step %}

### Add optional Jira overrides

Export any Jira-specific optional values you need:

* `JIRA_CHILD_LEVELS`
* `JIRA_EXTRA_TICKET_FIELDS`
* `JIRA_NOTIFY_USERS`
* `JIRA_ON_PREM`
* `JIRA_VERIFY_SSL`
  {% endstep %}

{% step %}

### Run the target script

```bash
python3 <script>.py --settings settings
```

{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The run uses your Jira query and Jira connection overrides instead of the file values.

<details>

<summary>Legacy Jira custom field overrides</summary>

Use these overrides only when you publish to Jira custom fields:

* `JIRA_CUSTOM_FIELDS`
* `JIRA_SUMMARY_RICH_TEMPLATE`

</details>
{% endtab %}

{% tab title="Azure DevOps" %}
Use this when you are using Azure DevOps.

#### ✅ Prerequisites

* Your `settings` file already works for the shared settings.
* You know the Azure DevOps authorization value.
* Your WIQL already returns the target work items.

#### 🚀 Steps

{% stepper %}
{% step %}

### Export the Azure DevOps query and connection values

```bash
export ADO_AUTHORIZATION="Basic base64-pat-token"
export ADO_ORGANIZATION="your-organization"
export ADO_PROJECT="your-project"
export ADO_WIQL="SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'User Story'"
```

{% endstep %}

{% step %}

### Add optional Azure DevOps overrides

Export any Azure DevOps-specific optional values you need:

* `ADO_CHILD_LEVELS`
* `ADO_EXTRA_TICKET_FIELDS`
* `ADO_VERIFY_SSL`
  {% endstep %}

{% step %}

### Run the target script

```bash
python3 <script>.py --settings settings
```

{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The run uses your WIQL and Azure DevOps connection overrides instead of the file values.
{% endtab %}
{% endtabs %}

#### Reference table

| Environment Variable               | Settings Path                      | Type       | Description                                                                |
| ---------------------------------- | ---------------------------------- | ---------- | -------------------------------------------------------------------------- |
| `OUTPUT_FOLDER`                    | `output_folder`                    | string     | Directory for generated reports                                            |
| `SEALIGHTS_API_TOKEN`              | `sealights.api_token`              | string     | SeaLights API authentication token                                         |
| `SEALIGHTS_DOMAIN`                 | `sealights.domain`                 | string     | SeaLights domain, for example `company.sealights.co`                       |
| `SEALIGHTS_COVERAGE_DAYS_BACK`     | `sealights.coverage_days_back`     | integer    | Days to look back for coverage data                                        |
| `SEALIGHTS_REPORT_TIMEOUT_MINUTES` | `sealights.report_timeout_minutes` | integer    | Report generation timeout in minutes                                       |
| `SEALIGHTS_USE_REPOSITORY_URL`     | `sealights.use_repository_url`     | boolean    | Use repository URL from SeaLights if available                             |
| `SEALIGHTS_VERIFY_SSL`             | `sealights.verify_ssl`             | boolean    | Verify SSL certificates                                                    |
| `KEY_PATTERN_REGEX`                | `scm.key_pattern_regex`            | string     | Regex to extract ticket IDs                                                |
| `GITHUB_API_URL`                   | `scm.github_api_url`               | string     | GitHub API URL                                                             |
| `GITHUB_TOKEN`                     | `scm.github_token`                 | string     | GitHub personal access token                                               |
| `GITHUB_OWNER`                     | `scm.github_owner`                 | string     | GitHub organization or user                                                |
| `SCM_TYPE`                         | `scm.type`                         | string     | SCM type: `github`, `gitlab`, `bitbucket`, or `ado`                        |
| `SCM_VERIFY_SSL`                   | `scm.verify_ssl`                   | boolean    | Verify SSL certificates for SCM API calls                                  |
| `SCM_REMOVE_PREFIX_REGEX`          | `scm.remove_prefix_regex`          | string     | Regex to strip from branch names                                           |
| `JIRA_AUTHORIZATION`               | `jira.authorization`               | string     | Jira authorization header value                                            |
| `JIRA_GET_LIST_JQL`                | `jira.jql`                         | string     | JQL query to fetch tickets                                                 |
| `JIRA_CHILD_LEVELS`                | `jira.child_levels`                | integer    | Number of child levels to traverse                                         |
| `JIRA_BASE_URL`                    | `jira.base_url`                    | string     | Jira instance base URL                                                     |
| `JIRA_API_VERSION`                 | `jira.api_version`                 | integer    | Jira API version, usually `2` or `3`                                       |
| `JIRA_CUSTOM_FIELDS`               | `jira.jira_custom_fields`          | JSON       | Custom field mappings for coverage data                                    |
| `JIRA_EXTRA_TICKET_FIELDS`         | `jira.extra_ticket_fields`         | JSON array | Additional fields to pull from tickets                                     |
| `JIRA_NOTIFY_USERS`                | `jira.notify_users`                | boolean    | Whether Jira updates should notify users                                   |
| `JIRA_ON_PREM`                     | `jira.on_prem`                     | boolean    | Update the Jira summary field as plain multi-line text instead of Jira ADF |
| `JIRA_VERIFY_SSL`                  | `jira.verify_ssl`                  | boolean    | Verify SSL certificates for Jira API calls                                 |
| `JIRA_SUMMARY_RICH_TEMPLATE`       | `jira.summary_rich_template`       | JSON       | Inline template override for `jira.jira_custom_fields.summary_rich`        |
| `ADO_WIQL`                         | `ado.wiql`                         | string     | WIQL query to fetch work items                                             |
| `ADO_AUTHORIZATION`                | `ado.authorization`                | string     | Azure DevOps authorization header                                          |
| `ADO_ORGANIZATION`                 | `ado.organization`                 | string     | Azure DevOps organization name                                             |
| `ADO_PROJECT`                      | `ado.project`                      | string     | Azure DevOps project name                                                  |
| `ADO_CHILD_LEVELS`                 | `ado.child_levels`                 | integer    | Number of child levels to traverse                                         |
| `ADO_EXTRA_TICKET_FIELDS`          | `ado.extra_ticket_fields`          | JSON array | Additional work item fields                                                |
| `ADO_VERIFY_SSL`                   | `ado.verify_ssl`                   | boolean    | Verify SSL certificates for Azure DevOps API calls                         |
| `CONFLUENCE_AUTHORIZATION`         | `confluence.authorization`         | string     | Confluence authorization header                                            |
| `CONFLUENCE_BASE_URL`              | `confluence.base_url`              | string     | Confluence instance URL                                                    |
| `CONFLUENCE_SPACE_KEY`             | `confluence.space_key`             | string     | Confluence space key                                                       |
| `CONFLUENCE_ANCESTOR_ID`           | `confluence.ancestor_id`           | string     | Parent page ID for reports                                                 |
| `CONFLUENCE_NOTE`                  | `confluence.note`                  | string     | Note text for Confluence pages                                             |
| `CONFLUENCE_EXTRA_SUMMARY_FIELDS`  | `confluence.extra_summary_fields`  | JSON array | Extra fields for summary table                                             |
| `CONFLUENCE_SUMMARY_PAGE_TITLE`    | `confluence.summary_page_title`    | string     | Title for summary page                                                     |
| `CONFLUENCE_DETAILS_PAGE_PREFIX`   | `confluence.details_page_prefix`   | string     | Prefix for detail page titles                                              |
| `CONFLUENCE_ON_PREM`               | `confluence.on_prem`               | boolean    | Use Confluence Server or Data Center APIs instead of Cloud APIs            |
| `CONFLUENCE_REPORT_FORMAT`         | `confluence.report_format`         | JSON       | Report format settings                                                     |
| `CONFLUENCE_QUALITY_GATE`          | `confluence.quality_gate`          | JSON       | Backward-compatible fallback for top coverage thresholds                   |
| `CONFLUENCE_VERIFY_SSL`            | `confluence.verify_ssl`            | boolean    | Verify SSL certificates for Confluence API calls                           |
| `TEST_STAGES`                      | `test_stages`                      | JSON array | Test stage definitions                                                     |
| `GROUPED_TEST_STAGES`              | `grouped_test_stages`              | JSON array | Aggregated test stage groups                                               |
| `COVERAGE_APP_LIST`                | `coverage_app_list`                | JSON array | Apps and branches to get coverage from                                     |
| `REPO_LIST`                        | `repo_list`                        | JSON array | Repository configurations                                                  |

#### Publication target overrides

Use these overrides when the published destination changes by platform.

{% tabs %}
{% tab title="Confluence" %}
Use this when you are using Confluence.

#### ✅ Prerequisites

* Report data already exists.
* The target space and parent page are known.
* The Confluence authorization value already works.

#### 🚀 Steps

{% stepper %}
{% step %}

### Export the Confluence connection values

```bash
export CONFLUENCE_AUTHORIZATION="Basic base64-credentials"
export CONFLUENCE_BASE_URL="https://yourcompany.atlassian.net"
export CONFLUENCE_SPACE_KEY="DEV"
export CONFLUENCE_ANCESTOR_ID="123456789"
```

{% endstep %}

{% step %}

### Add optional Confluence publishing values

Export any Confluence-specific optional values you need:

* `CONFLUENCE_NOTE`
* `CONFLUENCE_EXTRA_SUMMARY_FIELDS`
* `CONFLUENCE_SUMMARY_PAGE_TITLE`
* `CONFLUENCE_DETAILS_PAGE_PREFIX`
* `CONFLUENCE_REPORT_FORMAT`
* `CONFLUENCE_QUALITY_GATE`
* `CONFLUENCE_VERIFY_SSL`
  {% endstep %}

{% step %}

### Run the publishing script

```bash
python3 US3_RPT_create_confluence_reports.py --settings settings
```

{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The run publishes detailed coverage pages to the configured Confluence target.
{% endtab %}

{% tab title="Jira" %}
Use this when you are using Jira.

#### ✅ Prerequisites

* Report data already exists.
* Jira source settings already work.
* The target Jira publishing mode is known.

#### 🚀 Steps

{% stepper %}
{% step %}

### Export the Jira connection values

```bash
export JIRA_AUTHORIZATION="Basic base64-encoded-credentials"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
```

{% endstep %}

{% step %}

### Add the Jira publishing overrides

Export any Jira-specific publishing values you need:

* `JIRA_CUSTOM_FIELDS`
* `JIRA_EXTRA_TICKET_FIELDS`
* `JIRA_NOTIFY_USERS`
* `JIRA_ON_PREM`
* `JIRA_SUMMARY_RICH_TEMPLATE`
* `JIRA_VERIFY_SSL`
  {% endstep %}

{% step %}

### Run the matching publish script

Choose the Jira plugin or legacy custom-field command in the **Publish Analytics** section below.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The run publishes issue-level coverage to the configured Jira target.
{% endtab %}

{% tab title="Azure DevOps" %}
Use this when you are using Azure DevOps.

#### ✅ Prerequisites

* Report data already exists.
* Azure DevOps source settings already work.
* The Azure DevOps plugin is available for KPI publishing.

#### 🚀 Steps

{% stepper %}
{% step %}

### Export the Azure DevOps connection values

```bash
export ADO_AUTHORIZATION="Basic base64-pat-token"
export ADO_ORGANIZATION="your-organization"
export ADO_PROJECT="your-project"
```

{% endstep %}

{% step %}

### Add optional Azure DevOps overrides

Export any Azure DevOps-specific optional values you need:

* `ADO_CHILD_LEVELS`
* `ADO_EXTRA_TICKET_FIELDS`
* `ADO_VERIFY_SSL`
  {% endstep %}

{% step %}

### Run the matching publish script

Use the Azure DevOps plugin command in the **Publish Analytics** section below.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The run publishes work item coverage to the configured Azure DevOps target.
{% endtab %}
{% endtabs %}

#### JSON values

Use JSON strings for arrays and objects:

```bash
export TEST_STAGES='[{"name":"Unit","reportJsonKey":"unit","reportTitle":"Unit Tests"}]'
export CONFLUENCE_REPORT_FORMAT='{"type":"single_page"}'
```

#### CI/CD usage

Use environment variables in CI/CD when you want secure secret injection:

```yaml
env:
  SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
  JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
```

Use [Security Considerations](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/security-considerations.md) for secret handling guidance.

### Source Tagging

Use these commands to tag code changes with ticket IDs. Use them when SeaLights auto-tagging is not enabled.

* Use `US_SRC_tag_repos_by_github_prs.py` to tag merged pull requests.
* Use `US_SRC_tag_repos_by_history.py` to tag commit history directly.
* Use `US_SRC_tag_repos_by_jira_github_prs.py` to start from Jira tickets linked to GitHub PRs.
* Use the lower-level tagging commands only for direct SeaLights updates.

<details>

<summary>US_SRC_tag_repos_by_github_prs.py</summary>

Tags repositories by processing GitHub pull requests.

**Source:** `US_SRC_tag_repos_by_github_prs.py`

#### Syntax

```bash
python3 US_SRC_tag_repos_by_github_prs.py --settings <file> (--days-back <days> | --since-date <date>) [--log-level <level>]
```

#### Options

| Option         | Required      | Type              | Default    | Description                                                                |
| -------------- | ------------- | ----------------- | ---------- | -------------------------------------------------------------------------- |
| `--settings`   | No            | string (multiple) | `settings` | Settings file(s). Can be specified multiple times to merge configurations. |
| `--days-back`  | Conditional\* | integer           | -          | Number of days back to search for PRs                                      |
| `--since-date` | Conditional\* | date              | -          | Date from when to capture changes. Format: `YYYY-MM-DD`                    |
| `--log-level`  | No            | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR`                                 |

*Either `--days-back` or `--since-date` is required.*

#### Examples

Tag PRs from the last 30 days:

```bash
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --days-back 30
```

Tag PRs since a specific date:

```bash
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --since-date 2026-01-01
```

Use debug logging:

```bash
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --days-back 7 --log-level DEBUG
```

</details>

<details>

<summary>US_SRC_tag_repos_by_history.py</summary>

Tags repositories by processing commit history.

**Source:** `US_SRC_tag_repos_by_history.py`

#### Syntax

```bash
python3 US_SRC_tag_repos_by_history.py --settings <file> (--days-back <days> | --since-date <date>) [--only_create_files] [--log-level <level>]
```

#### Options

| Option                | Required      | Type              | Default    | Description                                             |
| --------------------- | ------------- | ----------------- | ---------- | ------------------------------------------------------- |
| `--settings`          | No            | string (multiple) | `settings` | Settings file(s)                                        |
| `--days-back`         | Conditional\* | integer           | -          | Number of days back to search for commits               |
| `--since-date`        | Conditional\* | date              | -          | Date from when to capture changes. Format: `YYYY-MM-DD` |
| `--only_create_files` | No            | flag              | false      | Only create files. Do not update SeaLights              |
| `--log-level`         | No            | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR`              |

*Either `--days-back` or `--since-date` is required.*

#### Examples

Tag commits from the last 60 days:

```bash
python3 US_SRC_tag_repos_by_history.py --settings settings --days-back 60
```

Generate files without tagging:

```bash
python3 US_SRC_tag_repos_by_history.py --settings settings --days-back 30 --only_create_files
```

</details>

<details>

<summary>US_SRC_tag_repos_by_jira_github_prs.py</summary>

Tags repositories by processing Jira tickets linked to GitHub PRs.

**Source:** `US_SRC_tag_repos_by_jira_github_prs.py`

#### Syntax

```bash
python3 US_SRC_tag_repos_by_jira_github_prs.py --settings <file> (--days-back <days> | --since-date <date>) [--log-level <level>]
```

#### Options

| Option         | Required      | Type              | Default    | Description                                             |
| -------------- | ------------- | ----------------- | ---------- | ------------------------------------------------------- |
| `--settings`   | No            | string (multiple) | `settings` | Settings file(s)                                        |
| `--days-back`  | Conditional\* | integer           | -          | Number of days back to search for PRs                   |
| `--since-date` | Conditional\* | date              | -          | Date from when to capture changes. Format: `YYYY-MM-DD` |
| `--log-level`  | No            | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR`              |

*Either `--days-back` or `--since-date` is required.*

#### Examples

Process Jira tickets with PRs from the last 14 days:

```bash
python3 US_SRC_tag_repos_by_jira_github_prs.py --settings settings --days-back 14
```

</details>

<details>

<summary>US_SRC_tag_build_in_sealights.py</summary>

Tags a specific build in SeaLights with a ticket ID.

**Source:** `US_SRC_tag_build_in_sealights.py`

#### Syntax

```bash
python3 US_SRC_tag_build_in_sealights.py --domain <domain> --token <token> --ticket <ticket> --bsid <bsid> [--no-verify] [--log-level <level>]
```

#### Options

| Option        | Required | Type   | Default | Description                                       |
| ------------- | -------- | ------ | ------- | ------------------------------------------------- |
| `--domain`    | Yes      | string | -       | SeaLights domain. Example: `company.sealights.co` |
| `--token`     | Yes      | string | -       | SeaLights API or agent token                      |
| `--ticket`    | Yes      | string | -       | Ticket key or ID to tag                           |
| `--bsid`      | Yes      | string | -       | Build session ID to tag                           |
| `--no-verify` | No       | flag   | false   | Disable SSL certificate verification              |
| `--log-level` | No       | choice | INFO    | Logging level: `DEBUG`, `INFO`, or `ERROR`        |

#### Example

```bash
python3 US_SRC_tag_build_in_sealights.py \
  --domain company.sealights.co \
  --token your-api-token \
  --ticket PROJ-123 \
  --bsid abc123def456
```

</details>

<details>

<summary>US_SRC_tag_modified_in_sealights.py</summary>

Tags modified files directly in SeaLights.

**Source:** `US_SRC_tag_modified_in_sealights.py`

#### Syntax

```bash
python3 US_SRC_tag_modified_in_sealights.py --domain <domain> --token <token> --app_name <app> --branch_name <branch> (--file <file> | --ticket <ticket> --physical_path <path> --lines <json>) [--ignore_prefix] [--no-verify] [--log-level <level>]
```

#### Options

| Option            | Required        | Type       | Default | Description                                |
| ----------------- | --------------- | ---------- | ------- | ------------------------------------------ |
| `--domain`        | Yes             | string     | -       | SeaLights domain                           |
| `--token`         | Yes             | string     | -       | SeaLights API or agent token               |
| `--app_name`      | Yes             | string     | -       | Application name in SeaLights              |
| `--branch_name`   | Yes             | string     | -       | Branch name in SeaLights                   |
| `--file`          | Conditional\*   | string     | -       | Path to file containing tagging data       |
| `--ticket`        | Conditional\*\* | string     | -       | Ticket key                                 |
| `--physical_path` | Conditional\*\* | string     | -       | File physical path                         |
| `--lines`         | Conditional\*\* | JSON array | -       | Modified lines in JSON format              |
| `--ignore_prefix` | No              | flag       | false   | Match physical path by suffix only         |
| `--no-verify`     | No              | flag       | false   | Disable SSL certificate verification       |
| `--log-level`     | No              | choice     | INFO    | Logging level: `DEBUG`, `INFO`, or `ERROR` |

*Use `--file` or the combination of `--ticket`, `--physical_path`, and `--lines`.*

**When not using `--file`, all three are required.**

#### Examples

Tag from a file:

```bash
python3 US_SRC_tag_modified_in_sealights.py \
  --domain company.sealights.co \
  --token your-token \
  --app_name my-app \
  --branch_name main \
  --file tagging_data.json
```

Tag a specific file directly:

```bash
python3 US_SRC_tag_modified_in_sealights.py \
  --domain company.sealights.co \
  --token your-token \
  --app_name my-app \
  --branch_name main \
  --ticket PROJ-123 \
  --physical_path src/main.py \
  --lines '[{"from": 10, "to": 25}]'
```

</details>

Use the **Report Generation** section below after tagging and [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) when tagging returns no changes or no tickets.

### Report Generation

Use these scripts after tagging is complete, or after SeaLights auto-tagging has already associated code changes with tickets.

{% stepper %}
{% step %}

### Build report data

Run `US1_RPT_create_report_info_files.py`.
{% endstep %}

{% step %}

### Generate HTML output

Run `US2_RPT_create_html_reports.py` when you need local HTML pages.
{% endstep %}

{% step %}

### Publish the results

Use the **Publish Analytics** section below when you need output outside the local report files.
{% endstep %}
{% endstepper %}

<details>

<summary>US1_RPT_create_report_info_files.py</summary>

Generates report data files from SeaLights for tickets.

**Source:** `US1_RPT_create_report_info_files.py`

#### Syntax

```bash
python3 US1_RPT_create_report_info_files.py --settings <file> [--ticket-source <source>] [--report-id <id>] [--log-level <level>]
```

#### Options

| Option            | Required | Type              | Default    | Description                                        |
| ----------------- | -------- | ----------------- | ---------- | -------------------------------------------------- |
| `--settings`      | No       | string (multiple) | `settings` | Settings file(s)                                   |
| `--ticket-source` | No       | choice            | jira       | Ticket source: `jira` or `ado`                     |
| `--report-id`     | No       | string            | -          | Existing coverage report ID. Skips report creation |
| `--log-level`     | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR`         |

Use these platform-specific variants when the ticket source changes by platform.

#### Jira

Use this when you are using Jira.

**✅ Prerequisites**

* Jira source settings already work.
* Tagged source data is already available.

**🚀 Steps**

{% stepper %}
{% step %}

### Select the Jira ticket source

Set `--ticket-source jira` when you want to build report data from Jira tickets.
{% endstep %}

{% step %}

### Run the report data command

```bash
python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source jira
```

{% endstep %}
{% endstepper %}

**📤 Expected Outcome**

The command generates report data from the Jira ticket scope.

#### Azure DevOps

Use this when you are using Azure DevOps.

**✅ Prerequisites**

* Azure DevOps source settings already work.
* Tagged source data is already available.

**🚀 Steps**

{% stepper %}
{% step %}

### Select the Azure DevOps ticket source

Set `--ticket-source ado` when you want to build report data from Azure DevOps work items.
{% endstep %}

{% step %}

### Run the report data command

```bash
python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source ado
```

{% endstep %}
{% endstepper %}

**📤 Expected Outcome**

The command generates report data from the Azure DevOps work item scope.

**Reuse an existing coverage report**

```bash
python3 US1_RPT_create_report_info_files.py --settings settings --report-id abc123def456
```

Skips report creation and reuses the given report ID — useful when regenerating output files without waiting for a new coverage analysis.

</details>

<details>

<summary>US2_RPT_create_html_reports.py</summary>

Generates HTML reports from `ReportInfo_*.json` files.

**Source:** `US2_RPT_create_html_reports.py`

#### Syntax

```bash
python3 US2_RPT_create_html_reports.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### Example

```bash
python3 US2_RPT_create_html_reports.py --settings settings
```

</details>

* Use [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) when reports return no tickets or no coverage.
* Use [Deployment patterns](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md) for runnable workflows.
* Use [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) for queries, app mapping, and test stages.

### Publish Analytics

Use these scripts after report data already exists. Most teams run them after `US1_RPT_create_report_info_files.py`.

* Use `US3_RPT_create_confluence_reports.py` to publish pages in Confluence.
* Use the `US4_RPT_*` scripts to publish coverage into Jira or Azure DevOps.
* Use the delete scripts only when you need to remove published coverage data.

<details>

<summary>US4_RPT_update_jira_plugin.py</summary>

Use this when you publish coverage values back to Jira through the Jira plugin API.

**Source:** `US4_RPT_update_jira_plugin.py`

#### Syntax

```bash
python3 US4_RPT_update_jira_plugin.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Report data already exists.
* Jira source settings already work.
* The Jira plugin is installed.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the Jira target

Verify that the Jira plugin path is the correct target for this rollout.
{% endstep %}

{% step %}

### Run the plugin updater

```bash
python3 US4_RPT_update_jira_plugin.py --settings settings
```

{% endstep %}

{% step %}

### Verify the published fields

Confirm the target issues show updated coverage values and summary content.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

Jira issues show updated plugin-based coverage values and summary content.

</details>

<details>

<summary>US_RPT_jira_plugin_delete_coverage.py</summary>

Use this when you need to remove coverage data from a specific Jira ticket.

**Source:** `US_RPT_jira_plugin_delete_coverage.py`

#### Syntax

```bash
python3 US_RPT_jira_plugin_delete_coverage.py <ticketId> --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `ticketId`    | Yes      | string            | -          | Jira ticket ID to delete coverage for      |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Report data already exists.
* Jira source settings already work.
* The Jira plugin is installed.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the target ticket

Verify the Jira ticket ID before you remove published coverage.
{% endstep %}

{% step %}

### Run the delete command

```bash
python3 US_RPT_jira_plugin_delete_coverage.py PROJ-123 --settings settings
```

{% endstep %}

{% step %}

### Verify the removal

Confirm the target issue no longer shows the published coverage data.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The selected Jira ticket no longer shows the published coverage data.

</details>

<details>

<summary>US_RPT_jira_plugin_delete_project_coverage.py</summary>

Use this when you need to remove coverage data from a full Jira project.

**Source:** `US_RPT_jira_plugin_delete_project_coverage.py`

#### Syntax

```bash
python3 US_RPT_jira_plugin_delete_project_coverage.py <project_key> --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `project_key` | Yes      | string            | -          | Jira project key to delete coverage for    |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Report data already exists.
* Jira source settings already work.
* The Jira plugin is installed.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the target project

Verify the Jira project key before you remove published coverage.
{% endstep %}

{% step %}

### Run the delete command

```bash
python3 US_RPT_jira_plugin_delete_project_coverage.py MYPROJECT --settings settings
```

{% endstep %}

{% step %}

### Verify the removal

Confirm the target project no longer shows the published coverage data.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The selected Jira project no longer shows the published coverage data.

</details>

<details>

<summary>US4_RPT_update_ado_plugin.py</summary>

Use this when you publish coverage values back to Azure DevOps through the ADO plugin API.

**Source:** `US4_RPT_update_ado_plugin.py`

#### Syntax

```bash
python3 US4_RPT_update_ado_plugin.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Report data already exists.
* Azure DevOps source settings already work.
* The ADO plugin is installed.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the Azure DevOps target

Verify that the ADO plugin path is the correct target for this rollout.
{% endstep %}

{% step %}

### Run the plugin updater

```bash
python3 US4_RPT_update_ado_plugin.py --settings settings
```

{% endstep %}

{% step %}

### Verify the published fields

Confirm the target work items show updated coverage values and summaries.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

Azure DevOps work items show updated plugin-based coverage values and summaries.

</details>

<details>

<summary>US4_RPT_update_jira.py</summary>

Use this when you are publishing coverage into legacy Jira custom fields.

**Source:** `US4_RPT_update_jira.py`

#### Syntax

```bash
python3 US4_RPT_update_jira.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Report data already exists.
* Jira source settings already work.
* The target custom field IDs are known.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the legacy target

Verify that the rollout still needs direct Jira custom field updates.
{% endstep %}

{% step %}

### Run the custom field updater

```bash
python3 US4_RPT_update_jira.py --settings settings
```

{% endstep %}

{% step %}

### Verify the published fields

Confirm the target issues show updated numeric coverage and summary fields.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

Jira custom fields show updated coverage values and summary content.

</details>

<details>

<summary>US3_RPT_create_confluence_reports.py</summary>

Use this when you publish shared coverage pages for wider review in Confluence.

**Source:** `US3_RPT_create_confluence_reports.py`

#### Syntax

```bash
python3 US3_RPT_create_confluence_reports.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Report data already exists.
* Confluence access already works.
* The target space and parent page are known.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the Confluence target

Verify the target space and parent page in your configuration.
{% endstep %}

{% step %}

### Run the Confluence publisher

```bash
python3 US3_RPT_create_confluence_reports.py --settings settings
```

{% endstep %}

{% step %}

### Verify the published pages

Confirm the summary page and related detail content were created or updated.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

Confluence receives the published coverage summary and related detail pages.

</details>

<details>

<summary>Azure DevOps Wiki</summary>

Use this when you are using Azure DevOps Wiki.

#### ✅ Prerequisites

* You need Azure DevOps-hosted documentation.
* A temporary Confluence target is available for current production use.

#### 🚀 Steps

{% stepper %}
{% step %}

### Keep the current production target

Continue publishing detailed pages to Confluence for the current rollout.
{% endstep %}

{% step %}

### Track the future destination

Keep Azure DevOps Wiki as the planned target for the later rollout.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

Detailed page publishing stays stable today, and the rollout path stays clear for Azure DevOps Wiki support.

{% hint style="info" %}
Azure DevOps Wiki support is planned by EOY2026.
{% endhint %}

</details>

* Publish only after report data is ready.
* Delete scripts remove already published coverage data.
* Test publishing in one project before rolling it out widely.
* Use [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) when publishing fails or fields stay empty.
* Use [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) for Confluence, Jira, and Azure DevOps settings.

### Utilities

Use these commands for diagnostics, helpers, and lower-level workflows. Most teams do not start here.

* Use the `US_SRC_git_*` and `US_SRC_github_*` commands to extract file changes.
* Use `US_jira_get_ticket_info.py` or `US_ado_get_ticket_info.py` to test ticket retrieval.

<details>

<summary>US_SRC_git_get_modified_from_history.py</summary>

Extracts modified files from git history.

**Source:** `US_SRC_git_get_modified_from_history.py`

#### Syntax

```bash
python3 US_SRC_git_get_modified_from_history.py --days_back <days> --regex <pattern> --folder <folder> --repo_name <repo> --app_name <app> [--log-level <level>]
```

#### Options

| Option        | Required | Type    | Default | Description                                |
| ------------- | -------- | ------- | ------- | ------------------------------------------ |
| `--days_back` | Yes      | integer | -       | Days back to look for code changes         |
| `--regex`     | Yes      | string  | -       | Regex pattern to extract ticket ID         |
| `--folder`    | Yes      | string  | -       | Folder to save results to                  |
| `--repo_name` | Yes      | string  | -       | Repository name in git                     |
| `--app_name`  | Yes      | string  | -       | Application name reported                  |
| `--log-level` | No       | choice  | INFO    | Logging level: `DEBUG`, `INFO`, or `ERROR` |

</details>

<details>

<summary>US_SRC_git_get_modified_from_branch.py</summary>

Gets modified files between the current branch and the base branch.

**Source:** `US_SRC_git_get_modified_from_branch.py`

#### Syntax

```bash
python3 US_SRC_git_get_modified_from_branch.py (--ticket-id <id> | --parse <method> --regex <pattern>) --filename <file> [--log-level <level>]
```

#### Options

| Option        | Required      | Type   | Default | Description                                |
| ------------- | ------------- | ------ | ------- | ------------------------------------------ |
| `--ticket-id` | Conditional\* | string | -       | Ticket ID. Bypasses extraction             |
| `--parse`     | Conditional\* | choice | -       | Extract from `name` or `comment`           |
| `--regex`     | Conditional\* | string | -       | Regex pattern to extract ticket ID         |
| `--filename`  | Yes           | string | -       | File to save results to                    |
| `--log-level` | No            | choice | INFO    | Logging level: `DEBUG`, `INFO`, or `ERROR` |

*Provide either `--ticket-id` or both `--parse` and `--regex`.*

</details>

<details>

<summary>US_SRC_github_get_modified_from_pr.py</summary>

Gets changed files for a specific GitHub pull request.

**Source:** `US_SRC_github_get_modified_from_pr.py`

#### Syntax

```bash
python3 US_SRC_github_get_modified_from_pr.py --github_api_url <url> --github_token <token> --repo_owner <owner> --repo_name <repo> --regex <pattern> --pr_number <number> --filename <file> [--log-level <level>]
```

#### Options

| Option             | Required | Type   | Default | Description                                |
| ------------------ | -------- | ------ | ------- | ------------------------------------------ |
| `--github_api_url` | Yes      | string | -       | GitHub API URL                             |
| `--github_token`   | Yes      | string | -       | GitHub personal access token               |
| `--repo_owner`     | Yes      | string | -       | GitHub repository owner                    |
| `--repo_name`      | Yes      | string | -       | GitHub repository name                     |
| `--regex`          | Yes      | string | -       | Regex pattern to extract ticket ID         |
| `--pr_number`      | Yes      | string | -       | Pull request number                        |
| `--filename`       | Yes      | string | -       | File to save results to                    |
| `--log-level`      | No       | choice | INFO    | Logging level: `DEBUG`, `INFO`, or `ERROR` |

</details>

<details>

<summary>US_jira_get_ticket_info.py</summary>

Fetches tickets from Jira using JQL.

**Source:** `US_jira_get_ticket_info.py`

#### Syntax

```bash
python3 US_jira_get_ticket_info.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Jira source settings already work.
* The JQL already returns the target issues in Jira.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the Jira query

Make sure the same JQL returns the expected issues in Jira.
{% endstep %}

{% step %}

### Run the Jira ticket lookup helper

```bash
python3 US_jira_get_ticket_info.py --settings settings
```

{% endstep %}

{% step %}

### Compare the returned issues

Confirm the returned issues match the expected Jira scope before you continue to report generation.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The helper returns the Jira issues selected by the configured JQL.

</details>

<details>

<summary>US_ado_get_ticket_info.py</summary>

Fetches work items from Azure DevOps using WIQL.

**Source:** `US_ado_get_ticket_info.py`

#### Syntax

```bash
python3 US_ado_get_ticket_info.py --settings <file> [--log-level <level>]
```

#### Options

| Option        | Required | Type              | Default    | Description                                |
| ------------- | -------- | ----------------- | ---------- | ------------------------------------------ |
| `--settings`  | No       | string (multiple) | `settings` | Settings file(s)                           |
| `--log-level` | No       | choice            | INFO       | Logging level: `DEBUG`, `INFO`, or `ERROR` |

#### ✅ Prerequisites

* Azure DevOps source settings already work.
* The WIQL already returns the target work items in Azure DevOps.

#### 🚀 Steps

{% stepper %}
{% step %}

### Confirm the WIQL

Make sure the same WIQL returns the expected work items in Azure DevOps.
{% endstep %}

{% step %}

### Run the Azure DevOps ticket lookup helper

```bash
python3 US_ado_get_ticket_info.py --settings settings
```

{% endstep %}

{% step %}

### Compare the returned work items

Confirm the returned work items match the expected Azure DevOps scope before you continue to report generation.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The helper returns the Azure DevOps work items selected by the configured WIQL.

</details>

* Test ticket lookup commands before debugging larger flows.
* Use these scripts when the main workflow needs deeper inspection.

Use the **Source Tagging** section above for the main tagging workflow and [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) when helper commands still fail.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.