CLI Reference

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

Command Categories

• Source Tagging Commands - Tag code changes with ticket IDs

• Report Generation Commands - Create coverage reports

• 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

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:

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

Tag PRs since a specific date:

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

Use debug logging:

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

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:

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

Generate files without tagging (dry run):

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

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:

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

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:

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

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:

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:

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

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:

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

Generate reports from Azure DevOps:

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

Use existing coverage report:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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

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

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

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

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

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:

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

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:

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:

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:

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 for complete environment variable list.

Debug Logging

Enable detailed logging for troubleshooting:

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 - Detailed settings documentation

• Examples - Real-world usage scenarios

• Troubleshooting - Common issues and solutions