CLI Reference

Find command categories, shared CLI patterns, and script execution flow for User Story Coverage.

Use this reference for exact CLI syntax, flags, examples, and execution order. Use Installation and first run for the fastest working flow.

What most teams run

1

Tag source changes

Run a US_SRC_* script unless SeaLights auto-tagging is enabled.

2

Generate report data

Run US1_RPT_create_report_info_files.py.

3

Build local HTML output

Run US2_RPT_* when you need local report pages.

4

Publish analytics

Run US3_RPT_* or US4_RPT_* when you need Confluence, Jira, or Azure DevOps output.

Shared CLI patterns and exit codes

Multiple settings files

Most scripts support repeated --settings flags:

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.

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 <script>.py --settings settings

Use this when you want CI-safe secret injection.

Debug logging

Run commands with debug logging when output looks wrong:

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

Exit codes

• 0 — success
• 1 — error. Check the logs.

Use Troubleshooting when a command fails and Deployment patterns for end-to-end workflows.

Environment variables

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

Use Installation and first run for the fastest working setup. Use Configuration for the full settings model.

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:

1

Export the variables you want to override

2

Run the target script

Platform-specific overrides

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

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

1

Export the Jira query and connection values

2

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

3

Run the target script

📤 Expected Outcome

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

Legacy Jira custom field overrides

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

• JIRA_CUSTOM_FIELDS
• JIRA_SUMMARY_RICH_TEMPLATE

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

1

Export the Azure DevOps query and connection values

2

Add optional Azure DevOps overrides

Export any Azure DevOps-specific optional values you need:

• ADO_CHILD_LEVELS
• ADO_EXTRA_TICKET_FIELDS
• ADO_VERIFY_SSL

3

Run the target script

📤 Expected Outcome

The run uses your WIQL and Azure DevOps connection overrides instead of the file values.

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.

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

1

Export the Confluence connection values

2

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

3

Run the publishing script

📤 Expected Outcome

The run publishes detailed coverage pages to the configured Confluence target.

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

1

Export the Jira connection values

2

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

3

Run the matching publish script

Choose the Jira plugin or legacy custom-field command in the Publish Analytics section below.

📤 Expected Outcome

The run publishes issue-level coverage to the configured Jira target.

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

1

Export the Azure DevOps connection values

2

Add optional Azure DevOps overrides

Export any Azure DevOps-specific optional values you need:

• ADO_CHILD_LEVELS
• ADO_EXTRA_TICKET_FIELDS
• ADO_VERIFY_SSL

3

Run the matching publish script

Use the Azure DevOps plugin command in the Publish Analytics section below.

📤 Expected Outcome

The run publishes work item coverage to the configured Azure DevOps target.

JSON values

Use JSON strings for arrays and objects:

CI/CD usage

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

Use Security Considerations 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.

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

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:

Tag PRs since a specific date:

Use debug logging:

US_SRC_tag_repos_by_history.py

Tags repositories by processing commit history.

Source: US_SRC_tag_repos_by_history.py

Syntax

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:

Generate files without tagging:

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

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:

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

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

US_SRC_tag_modified_in_sealights.py

Tags modified files directly in SeaLights.

Source: US_SRC_tag_modified_in_sealights.py

Syntax

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:

Tag a specific file directly:

Use the Report Generation section below after tagging and Troubleshooting 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.

1

Build report data

Run US1_RPT_create_report_info_files.py.

2

Generate HTML output

Run US2_RPT_create_html_reports.py when you need local HTML pages.

3

Publish the results

Use the Publish Analytics section below when you need output outside the local report files.

US1_RPT_create_report_info_files.py

Generates report data files from SeaLights for tickets.

Source: US1_RPT_create_report_info_files.py

Syntax

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

1

Select the Jira ticket source

Set --ticket-source jira when you want to build report data from Jira tickets.

2

Run the report data command

📤 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

1

Select the Azure DevOps ticket source

Set --ticket-source ado when you want to build report data from Azure DevOps work items.

2

Run the report data command

📤 Expected Outcome

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

Reuse an existing coverage report

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

US2_RPT_create_html_reports.py

Generates HTML reports from ReportInfo_*.json files.

Source: US2_RPT_create_html_reports.py

Syntax

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

• Use Troubleshooting when reports return no tickets or no coverage.
• Use Deployment patterns for runnable workflows.
• Use Configuration 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.

US4_RPT_update_jira_plugin.py

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

Source: US4_RPT_update_jira_plugin.py

Syntax

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

1

Confirm the Jira target

Verify that the Jira plugin path is the correct target for this rollout.

2

Run the plugin updater

3

Verify the published fields

Confirm the target issues show updated coverage values and summary content.

📤 Expected Outcome

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

US_RPT_jira_plugin_delete_coverage.py

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

Source: US_RPT_jira_plugin_delete_coverage.py

Syntax

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

1

Confirm the target ticket

Verify the Jira ticket ID before you remove published coverage.

2

Run the delete command

3

Verify the removal

Confirm the target issue no longer shows the published coverage data.

📤 Expected Outcome

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

US_RPT_jira_plugin_delete_project_coverage.py

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

Source: US_RPT_jira_plugin_delete_project_coverage.py

Syntax

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

1

Confirm the target project

Verify the Jira project key before you remove published coverage.

2

Run the delete command

3

Verify the removal

Confirm the target project no longer shows the published coverage data.

📤 Expected Outcome

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

US4_RPT_update_ado_plugin.py

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