# CLI Reference

Complete reference for all command-line scripts in the User Story Coverage Tagging toolkit.

## Command Categories

* [Source Tagging Commands](#source-tagging-commands) - Tag code changes with ticket IDs
* [Report Generation Commands](#report-generation-commands) - Create coverage reports
* [Utility Commands](#utility-commands) - Helper scripts for specific tasks

***

## Source Tagging Commands

These scripts extract ticket IDs from source control and tag modified code in SeaLights.

### US\_SRC\_tag\_repos\_by\_github\_prs.py

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

***

### US\_SRC\_tag\_repos\_by\_history.py

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, don't 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 (dry run):

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

***

### US\_SRC\_tag\_repos\_by\_jira\_github\_prs.py

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 last 14 days:

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

***

### US\_SRC\_tag\_build\_in\_sealights.py

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 (e.g., company.sealights.co) |
| `--token`     | Yes      | string | -       | SeaLights API or Agent token                  |
| `--ticket`    | Yes      | string | -       | Ticket key/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          |

#### Examples

Tag a build with a ticket:

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

***

### US\_SRC\_tag\_modified\_in\_sealights.py

Low-level utility to tag 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 (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 (`--ticket`, `--physical_path`, `--lines`) 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 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}]'
```

***

## Report Generation Commands

These scripts generate coverage reports in various formats.

### US1\_RPT\_create\_report\_info\_files.py

Generates report data files (JSON) 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                |

#### Examples

Generate reports from Jira tickets:

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

Generate reports from Azure DevOps:

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

Use existing coverage report:

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

***

### US2\_RPT\_create\_html\_reports.py

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 |

#### Examples

Generate HTML reports:

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

***

### US3\_RPT\_create\_confluence\_reports.py

Creates or updates Confluence pages with coverage reports.

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

#### Examples

Create Confluence pages:

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

***

### US4\_RPT\_update\_jira.py

Updates Jira Cloud tickets with coverage data in 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 |

#### Examples

Update Jira tickets:

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

***

### US4\_RPT\_update\_jira\_plugin.py

Updates Jira On-Premises via 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 |

#### Examples

Update Jira On-Prem plugin:

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

***

### US4\_RPT\_update\_ado\_plugin.py

Updates Azure DevOps via 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 |

#### Examples

Update ADO plugin:

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

***

## Utility Commands

Helper scripts for specific operations.

### US\_SRC\_git\_get\_modified\_from\_history.py

Extracts modified files from git history (library function).

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

***

### US\_SRC\_git\_get\_modified\_from\_branch.py

Gets modified files between current branch and 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 (branch name) or comment (commit message) |
| `--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`*

***

### US\_SRC\_github\_get\_modified\_from\_pr.py

Gets PR changes for a specific GitHub PR.

**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 (e.g., <https://api.github.com>) |
| `--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            |

***

### US\_jira\_get\_ticket\_info.py

Fetches tickets from Jira using JQL (library function).

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

***

### US\_ado\_get\_ticket\_info.py

Fetches work items from Azure DevOps using WIQL (library function).

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

***

### US\_RPT\_jira\_plugin\_delete\_coverage.py

Deletes coverage data for 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 (positional) | 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  |

#### Examples

Delete coverage for a ticket:

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

***

### US\_RPT\_jira\_plugin\_delete\_project\_coverage.py

Deletes all coverage data for a 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 (positional) | 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    |

#### Examples

Delete all coverage for a project:

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

***

## Common Patterns

### Multiple Settings Files

Most scripts support loading multiple settings files that are merged together:

```bash
python3 US1_RPT_create_report_info_files.py \
  --settings base_settings \
  --settings env_specific \
  --settings credentials
```

### Using 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 US1_RPT_create_report_info_files.py --settings settings
```

See [Configuration Guide](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) for complete environment variable list.

### Debug Logging

Enable detailed logging for troubleshooting:

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

***

## Exit Codes

All scripts use standard exit codes:

* `0` - Success
* `1` - Error (check logs for details)

***

## Next Steps

* [Configuration Guide](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) - Detailed settings documentation
* [Examples](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md) - Real-world usage scenarios
* [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) - Common issues and solutions


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.