CLI Reference

Complete command-line interface reference for nhl-scrabble.

Synopsis

nhl-scrabble [OPTIONS] COMMAND [ARGS]...

Global Options

Option	Description
`-V, --version`	Show version and exit
`-h, --help`	Show help message and exit

Commands

`analyze`

Run the NHL Scrabble score analyzer.

Synopsis:

nhl-scrabble analyze [OPTIONS]

Description:

Fetches current NHL roster data from the official NHL API and calculates Scrabble scores for all player names. Generates comprehensive reports showing team, division, and conference standings based on Scrabble scores.

Options:

Option	Type	Default	Description
`-f, --format FORMAT`	choice	`text`	Output format: `text`, `json`, `csv`, `excel`
`-o, --output PATH`	path	stdout	Output file path (writes to stdout if not given)
`-v, --verbose`	flag	false	Enable verbose logging (DEBUG level)
`-q, --quiet`	flag	false	Suppress progress bars
`--no-cache`	flag	false	Disable API response caching
`--clear-cache`	flag	false	Clear API cache before running
`--top-players INT`	int	20	Number of top players to show in rankings
`--top-team-players INT`	int	5	Number of top players per team to show
`-h, --help`	flag	false	Show command help and exit

Examples:

# Basic usage (output to stdout)
nhl-scrabble analyze

# Show help (short and long options)
nhl-scrabble analyze -h
nhl-scrabble analyze --help

# Save to file (short and long options)
nhl-scrabble analyze -o report.txt
nhl-scrabble analyze --output report.txt

# JSON format (short options)
nhl-scrabble analyze -f json -o report.json

# JSON format (long options)
nhl-scrabble analyze --format json --output report.json

# Verbose logging (short and long)
nhl-scrabble analyze -v
nhl-scrabble analyze --verbose

# Quiet mode - suppress progress bars
nhl-scrabble analyze -q

# Show more players
nhl-scrabble analyze --top-players 50 --top-team-players 10

# Fresh data (bypass cache)
nhl-scrabble analyze --no-cache

# Clear cache and run
nhl-scrabble analyze --clear-cache

# Combine options (short options for brevity)
nhl-scrabble analyze -f json -o report.json -v --top-players 100

# Mix short and long options (both work!)
nhl-scrabble analyze -f json --output report.json -v

Output:

The command generates a comprehensive report with the following sections:

Header - Tool name and version
Conference Standings - Eastern and Western conference rankings
Division Standings - All 4 divisions with team rankings
Mock Playoff Bracket - Simulated playoff seeding
Team Details - Individual team breakdowns with top players
Top Players - League-wide player rankings
Statistical Summary - League statistics and distributions

See Understanding Output Tutorial for details.

Performance:

Fetch time: ~5-15 seconds (depends on network and NHL API)
Processing time: <1 second
Total runtime: ~6-16 seconds typically

With caching enabled (default), subsequent runs complete in <2 seconds.

Error Handling:

The command validates output paths before fetching data. Common errors:

Error	Cause	Solution
“Output directory does not exist”	Parent directory of –output doesn’t exist	Create directory first
“Output directory is not writable”	No write permission to directory	Check permissions
“Output file exists but is not writable”	Existing file is read-only	Change file permissions
“NHL API Error”	Network or API issue	Check connection, retry

`interactive`

Start interactive mode for exploring NHL Scrabble data.

Synopsis:

nhl-scrabble interactive [OPTIONS]

Description:

Interactive mode provides a REPL (Read-Eval-Print Loop) for exploring NHL Scrabble scores through commands like show, top, compare, and more. Allows dynamic exploration without re-running the full analysis.

Options:

Option	Type	Default	Description
`--no-fetch`	flag	false	Skip fetching data from NHL API on startup
`-v, --verbose`	flag	false	Enable verbose logging (DEBUG level)
`--help`	flag	false	Show command help and exit

Examples:

# Start interactive mode
nhl-scrabble interactive

# Skip initial data fetch
nhl-scrabble interactive --no-fetch

# Verbose logging
nhl-scrabble interactive --verbose

Interactive Commands:

Once in interactive mode, you can use commands like:

show - Display team standings
top - Show top players
compare - Compare players or teams
filter - Filter by division or conference
help - Show available commands
exit or quit - Exit interactive mode

See the interactive mode help (help command) for full command details.

`search`

Search for NHL players by name with advanced filtering.

Synopsis:

nhl-scrabble search [QUERY] [OPTIONS]

Description:

Search the NHL player database by name with support for exact matching, fuzzy matching, and wildcard patterns. Filter results by Scrabble score, team, division, or conference.

Arguments:

Argument	Type	Required	Description
`QUERY`	string	no	Search query (name or pattern to search)

Options:

Option	Type	Default	Description
`-f, --fuzzy`	flag	false	Enable fuzzy matching for typo tolerance
`--min-score INT`	int	none	Filter players with score >= INT
`--max-score INT`	int	none	Filter players with score <= INT
`-t, --teams CODE`	string	none	Filter by team abbreviation (e.g., TOR, EDM)
`-d, --divisions NAME`	string	none	Filter by division name
`-c, --conferences NAME`	string	none	Filter by conference name (Eastern/Western)
`-n, --limit INT`	int	20	Maximum number of results to show (range: 1-500)
`-v, --verbose`	flag	false	Enable verbose logging (DEBUG level)
`-q, --quiet`	flag	false	Suppress progress bars and status messages
`--format FORMAT`	choice	`text`	Output format: `text` or `json`
`-o, --output PATH`	path	stdout	Output file path (writes to stdout if not given)
`--help`	flag	false	Show command help and exit

Examples:

# Exact search
nhl-scrabble search "Connor McDavid"

# Fuzzy search (tolerates typos)
nhl-scrabble search McDavd --fuzzy

# Wildcard search
nhl-scrabble search "Connor*"

# Find high-scoring players
nhl-scrabble search --min-score 50

# Find players on a team
nhl-scrabble search --teams TOR

# Combine filters
nhl-scrabble search "Connor*" --teams EDM --min-score 30

# Show more results
nhl-scrabble search McDavid --fuzzy --limit 50

# JSON output
nhl-scrabble search --min-score 60 --format json --output high-scorers.json

# Division search
nhl-scrabble search --divisions Pacific --min-score 35

# Conference search
nhl-scrabble search --conferences Eastern --limit 100

Search Modes:

Exact Search (default): Case-insensitive substring matching

nhl-scrabble search "McDavid"  # Finds "Connor McDavid"

Fuzzy Search: Uses similarity matching to handle typos

nhl-scrabble search "McDavd" --fuzzy  # Still finds "McDavid"

Wildcard Search: Supports * (any chars) and ? (single char)

nhl-scrabble search "Connor*"    # Finds all "Connor ..."
nhl-scrabble search "?lex*"      # Finds "Alex ..."

Output:

Text format shows:

Search parameters used
Number of results found
Player details: name, score, team, division
Score breakdown (first name + last name)

JSON format includes:

Query information
Result count
Database statistics
Full player data as array

Performance:

First search: ~5-15 seconds (fetches all player data)
Subsequent searches: <2 seconds (uses cached data)
Search time: <0.1 seconds (instant once data is loaded)

Filtering:

Filters can be combined and are applied in order:

Team filter
Division filter
Conference filter
Score range filters
Name search
Result limit

Error Handling:

Error	Cause	Solution
“NHL API Error”	Network or API issue	Check connection
“No players found”	No matches for criteria	Broaden search
“Invalid team code”	Unknown team abbreviation	Use valid code

Future Commands (Planned)

nhl-scrabble compare (Planned)

Compare teams or players:

nhl-scrabble compare TOR BOS              # Compare two teams
nhl-scrabble compare --player "Ovechkin"  # Show player history

nhl-scrabble history (Planned)

Show historical trends:

nhl-scrabble history --team TOR           # Team score over time
nhl-scrabble history --league             # League-wide trends

nhl-scrabble export (Planned)

Export in various formats:

nhl-scrabble export --format csv         # CSV export
nhl-scrabble export --format html        # HTML report

Exit Codes

Code	Meaning
0	Success
1	General error (unspecified)
2	Invalid command-line arguments

Environment Variables

The CLI respects these environment variables (in addition to those in Environment Variables Reference):

Variable	Description	Default
`NHL_SCRABBLE_OUTPUT_FORMAT`	Default output format	`text`
`NHL_SCRABBLE_VERBOSE`	Enable verbose logging	`false`
`NHL_SCRABBLE_TOP_PLAYERS`	Default top players count	`20`
`NHL_SCRABBLE_TOP_TEAM_PLAYERS`	Default top team players	`5`
`NHL_SCRABBLE_CACHE_ENABLED`	Enable API caching	`true`

Priority: Command-line options override environment variables.

Example:

# Set defaults via environment
export NHL_SCRABBLE_OUTPUT_FORMAT=json
export NHL_SCRABBLE_VERBOSE=true

# Now these use the environment defaults
nhl-scrabble analyze                    # JSON format, verbose
nhl-scrabble analyze --format text      # Override to text

Configuration Files

Not yet supported. Configuration is via environment variables and command-line options only.

Planned: Support for ~/.nhl-scrabble/config.toml:

[output]
format = "json"
top_players = 50

[api]
timeout = 30
retries = 5

Shell Completion

Not yet implemented. Planned support for:

Bash
Zsh
Fish
PowerShell

Programmatic Usage

Instead of CLI, use NHL Scrabble as a Python library:

from nhl_scrabble.cli import run_analysis
from nhl_scrabble.config import Config

config = Config(output_format="json", verbose=True, top_players_count=50)

result = run_analysis(config)
print(result)

See Python API Reference for details.

Logging

Control logging verbosity:

# Standard output (INFO level)
nhl-scrabble analyze

# Verbose output (DEBUG level)
nhl-scrabble analyze --verbose

# Quiet output (WARNING level) - not yet implemented
nhl-scrabble analyze --quiet

Log format:

2026-04-16 19:00:00 - nhl_scrabble.api.nhl_client - INFO - Fetching standings...
2026-04-16 19:00:01 - nhl_scrabble.api.nhl_client - DEBUG - GET https://api-web.nhle.com/v1/standings/now
2026-04-16 19:00:02 - nhl_scrabble.api.nhl_client - INFO - Successfully fetched 32 teams

Log locations:

stdout: Standard and verbose logging
stderr: Error messages
Files: Not supported (use shell redirection if needed)

Examples by Use Case

Basic Analysis

# Run and view in terminal
nhl-scrabble analyze

# Save to file for later
nhl-scrabble analyze -o report.txt

# View saved report
cat report.txt

Data Export

# Export as JSON
nhl-scrabble analyze --format json -o data.json

# Import to spreadsheet
python -m json.tool data.json > formatted.json
# Open in Excel/Sheets

# Query with jq
cat data.json | jq '.teams.TOR.total'

Development & Debugging

# Verbose output
nhl-scrabble analyze --verbose

# Fresh data (no cache)
nhl-scrabble analyze --no-cache --verbose

# Clear cache
nhl-scrabble analyze --clear-cache

Custom Reports

# Show top 100 players
nhl-scrabble analyze --top-players 100

# Show top 10 players per team
nhl-scrabble analyze --top-team-players 10

# Combine both
nhl-scrabble analyze --top-players 100 --top-team-players 10 -o full-report.txt

CLI Reference

Synopsis

Global Options

Commands

analyze

interactive

search

Future Commands (Planned)

Exit Codes

Environment Variables

Configuration Files

Shell Completion

Programmatic Usage

Logging

Examples by Use Case

Basic Analysis

Data Export

Development & Debugging

Custom Reports

Related

`analyze`

`interactive`

`search`