CLI Reference

The bc_dev_tools package provides a non-interactive CLI for repeatable runs, automation, and scripting. All commands are invoked through the package entry point:

python -m bc_dev_tools <command> [options]

Running without a subcommand prints the help message. There is no default command.

Top-Level Commands

pipeline

Run the full import, normalize, compare, and export pipeline end to end.

python -m bc_dev_tools pipeline [--threshold FLOAT]

Flag	Type	Default	Description
--threshold	float	0.85	Similarity threshold for fuzzy matching (0.0 - 1.0)

Example:

python -m bc_dev_tools pipeline --threshold 0.90

compare

Fuzzy-match BC fault codes against FAQ issue types. Both datasets must already be imported into the SQLite database.

python -m bc_dev_tools compare [--threshold FLOAT]

Flag	Type	Default	Description
--threshold	float	0.85	Similarity threshold for fuzzy matching (0.0 - 1.0)

Example:

python -m bc_dev_tools compare --threshold 0.80

export

Export comparison results to an Excel workbook with All Results, Matched, and Unmatched sheets.

python -m bc_dev_tools export [--output PATH]

Flag	Type	Default	Description
--output, -o	string	comparison_results.xlsx	Output file path

Example:

python -m bc_dev_tools export --output results_march.xlsx

submit

Submit quality reports from an Excel file to the CSM 1.0 API. Each row is sent as a separate API call. Results and logs are written to submission_results.xlsx and api_logs_<timestamp>.txt.

python -m bc_dev_tools submit --file PATH

Flag	Type	Default	Description
--file, -f	string	required	Excel file containing submissions

Example:

python -m bc_dev_tools submit --file "Failed_PSI.xlsx"

interactive

Launch the interactive numbered menu. This is equivalent to the legacy python main.py invocation.

python -m bc_dev_tools interactive

No flags. The menu prompts for all inputs.

Import Commands

Grouped under the import subcommand. Running python -m bc_dev_tools import without a source prints the import help.

import faq

Import FAQ issue types from the FAQ REST API and normalize into relational dimension tables.

python -m bc_dev_tools import faq

No flags. Uses FAQ_API_BASE_URL, FAQ_API_USERNAME, and FAQ_API_PASSWORD from environment variables.

import bc

Import BC fault code relationships from an Excel file and normalize.

python -m bc_dev_tools import bc [--file PATH]

Flag	Type	Default	Description
--file, -f	string	Configured BC_FAULT_CODES_FILE	Custom Excel file path

Example:

python -m bc_dev_tools import bc --file "updated_fault_codes.xlsx"

import excel

Import other Excel files into SQLite. Without --file, imports all files listed in OTHER_EXCEL_FILES in config.py.

python -m bc_dev_tools import excel [--file PATH] [--table-name NAME]

Flag	Type	Default	Description
--file, -f	string	All configured files	Import a specific file instead of all
--table-name	string	Auto-generated from filename	Custom SQLite table name (only with --file)

Example:

python -m bc_dev_tools import excel --file "ServiceItems.xlsx" --table-name service_items

import manual-report

Import the manual CSM quality report compilation spreadsheet (Manual CSM Quality Report Compilation - 2024.xlsx).

python -m bc_dev_tools import manual-report

No flags. The file path and table name are hardcoded in the handler.

Resolve Commands

Grouped under the resolve subcommand. Running python -m bc_dev_tools resolve without an operation prints the resolve help.

resolve run

Run the Failed CSM Submissions Resolver pipeline. Fetches failed service orders from BC OData, matches against the FAQ hierarchy, and writes results to the output spreadsheet.

python -m bc_dev_tools resolve run [OPTIONS]

Flag	Type	Default	Description
--dry-run	flag	off	Fetch and process data but do not write to the spreadsheet
--threshold	float	0.85	Similarity threshold for FAQ matching
--full	flag	off	Ignore last-run state and fetch the entire backlog
--since	string	last-run date	Custom cutoff date (YYYY-MM-DD)
--tab-name, -t	string	Current month	Spreadsheet tab name
--output, -o	string	FAILED_CSM_SPREADSHEET env var	Output spreadsheet path
--submit	flag	off	Submit matched rows to the CSM 1.0 API
--mark-sent	flag	off	After CSM submission, set csmQualitySent=true in BC
--backfill-sent	string	none	Backfill "Sent to CSM" column (YYYY-MM-DD HH:MM). Skips the normal pipeline.
--verbose, -v	flag	off	Enable verbose logging

Examples:

# Dry run to preview what would be written
python -m bc_dev_tools resolve run --dry-run --verbose

# Full backlog with submission and BC update
python -m bc_dev_tools resolve run --full --submit --mark-sent

# Custom date range and output
python -m bc_dev_tools resolve run --since 2026-01-01 --output ~/Desktop/resolver_output.xlsx

# Backfill sent timestamps (skips the normal fetch/match pipeline)
python -m bc_dev_tools resolve run --backfill-sent "2026-03-15 14:30"

resolve analyze

Run pattern analysis on the resolver output spreadsheet.

python -m bc_dev_tools resolve analyze

No flags. Reads from the FAILED_CSM_SPREADSHEET path.

resolve corrections

Analyze human correction patterns in the resolver output.

python -m bc_dev_tools resolve corrections

No flags. Reads from the FAILED_CSM_SPREADSHEET path.

Backwards Compatibility

The failed_csm_resolver.py module can still be run as a standalone script for backwards compatibility:

python -m bc_dev_tools.failed_csm_resolver [OPTIONS]

This accepts the same flags as resolve run. The preferred invocation is through the unified CLI.

Environment Variables

All API credentials and configuration are provided via environment variables. See .env.example for the full list and README.md for descriptions.

Exit Codes

Code	Meaning
0	Success
1	Runtime error (missing tools directory, missing config)
2	Invalid arguments or missing subcommand
other	Uncaught exception (a stack trace will be printed)