Environment Variables Reference

Complete list of all environment variables supported by NHL Scrabble.

Quick Reference

Variable

Type

Default

Description

NHL_SCRABBLE_API_TIMEOUT

int

10

API timeout (seconds)

NHL_SCRABBLE_API_RETRIES

int

3

Retry attempts

NHL_SCRABBLE_RATE_LIMIT_DELAY

float

0.3

Request delay (seconds)

NHL_SCRABBLE_MAX_CONCURRENT

int

5

Concurrent API requests

NHL_SCRABBLE_CACHE_ENABLED

bool

true

Enable caching

NHL_SCRABBLE_CACHE_EXPIRY

int

3600

Cache duration (seconds)

NHL_SCRABBLE_OUTPUT_FORMAT

string

text

Output format

NHL_SCRABBLE_LANG

string

en_US

Display locale

NHL_SCRABBLE_TOP_PLAYERS

int

20

Top players count

NHL_SCRABBLE_TOP_TEAM_PLAYERS

int

5

Per-team players

NHL_SCRABBLE_VERBOSE

bool

false

Verbose logging

NHL_SCRABBLE_SANITIZE_LOGS

bool

true

Sanitize secrets

NHL_SCRABBLE_WEB_HOST

string

127.0.0.1

Web server host

NHL_SCRABBLE_WEB_PORT

int

8000

Web server port

NHL_SCRABBLE_WEB_WORKERS

int

4

Gunicorn workers

NHL_SCRABBLE_CORS_ORIGINS

string

http://localhost:8000,…

Allowed CORS origins

NHL_SCRABBLE_CACHE_TTL

int

3600

Web cache TTL (seconds)

NHL_SCRABBLE_LOG_LEVEL

string

INFO

Logging level

NHL_SCRABBLE_LOG_FORMAT

string

text

Log format (text/json)

NO_COLOR

bool

-

Disable color output

TERM

string

(system)

Terminal type

API Configuration

NHL_SCRABBLE_API_TIMEOUT

Type: Integer Default: 10 Description: Maximum time in seconds to wait for API response.

Example:

export NHL_SCRABBLE_API_TIMEOUT=30

NHL_SCRABBLE_API_RETRIES

Type: Integer Default: 3 Description: Number of retry attempts on API failure.

Example:

export NHL_SCRABBLE_API_RETRIES=5

NHL_SCRABBLE_RATE_LIMIT_DELAY

Type: Float Default: 0.3 Description: Delay in seconds between API requests to respect rate limits.

Example:

export NHL_SCRABBLE_RATE_LIMIT_DELAY=0.5

NHL_SCRABBLE_MAX_CONCURRENT

Type: Integer Default: 5 Description: Maximum number of concurrent API requests for fetching team rosters.

Controls parallelism when fetching NHL team data. Higher values provide better performance but may trigger rate limiting. Recommended range: 5-10.

Performance Impact:

  • 1 (sequential): ~10 seconds for 32 teams

  • 5 (default): ~2 seconds for 32 teams (5x speedup)

  • 10 (high): ~1.5 seconds for 32 teams (7x speedup)

Example:

# Conservative (safe, reliable)
export NHL_SCRABBLE_MAX_CONCURRENT=3

# Default (balanced performance)
export NHL_SCRABBLE_MAX_CONCURRENT=5

# Aggressive (maximum performance)
export NHL_SCRABBLE_MAX_CONCURRENT=10

# Sequential (debugging, no parallelism)
export NHL_SCRABBLE_MAX_CONCURRENT=1

Caching

NHL_SCRABBLE_CACHE_ENABLED

Type: Boolean Default: true Description: Enable/disable API response caching.

Example:

export NHL_SCRABBLE_CACHE_ENABLED=false

NHL_SCRABBLE_CACHE_EXPIRY

Type: Integer Default: 3600 Description: Cache expiration time in seconds.

Example:

export NHL_SCRABBLE_CACHE_EXPIRY=7200  # 2 hours

Output

NHL_SCRABBLE_OUTPUT_FORMAT

Type: String (text|json) Default: text Description: Default output format.

Example:

export NHL_SCRABBLE_OUTPUT_FORMAT=json

NHL_SCRABBLE_LANG

Type: String (locale code) Default: en_US Description: Display locale for translations and number formatting.

Supported Locales:

Locale

Language

Region

en_US

English

United States

en_CA

English

Canada

fr_CA

French

Canada

sv_SE

Swedish

Sweden

ru_RU

Russian

Russia

fi_FI

Finnish

Finland

cs_CZ

Czech

Czechia

de_DE

German

Germany

de_CH

German

Switzerland

it_CH

Italian

Switzerland

sk_SK

Slovak

Slovakia

lv_LV

Latvian

Latvia

Examples:

# French Canadian
export NHL_SCRABBLE_LANG=fr_CA

# Swedish
export NHL_SCRABBLE_LANG=sv_SE

# Default (US English)
unset NHL_SCRABBLE_LANG

Note: Translations must be compiled with pybabel compile before use. See Translation Workflow for details.

NHL_SCRABBLE_TOP_PLAYERS

Type: Integer Default: 20 Description: Number of top players to show in league rankings.

Example:

export NHL_SCRABBLE_TOP_PLAYERS=50

NHL_SCRABBLE_TOP_TEAM_PLAYERS

Type: Integer Default: 5 Description: Number of top players to show per team.

Example:

export NHL_SCRABBLE_TOP_TEAM_PLAYERS=10

Logging

NHL_SCRABBLE_VERBOSE

Type: Boolean Default: false Description: Enable verbose (DEBUG level) logging.

Example:

export NHL_SCRABBLE_VERBOSE=true

NHL_SCRABBLE_SANITIZE_LOGS

Type: Boolean Default: true Description: Sanitize sensitive data (API keys, tokens) from logs.

Example:

export NHL_SCRABBLE_SANITIZE_LOGS=false  # Only for debugging

NHL_SCRABBLE_LOG_LEVEL

Type: String (DEBUG|INFO|WARNING|ERROR|CRITICAL) Default: INFO Description: Logging level for application logs.

Example:

export NHL_SCRABBLE_LOG_LEVEL=DEBUG  # Verbose logging
export NHL_SCRABBLE_LOG_LEVEL=WARNING  # Only warnings and errors

NHL_SCRABBLE_LOG_FORMAT

Type: String (text|json) Default: text Description: Log output format. Use json for structured logging in production.

Example:

export NHL_SCRABBLE_LOG_FORMAT=json  # Structured logs for parsing

NO_COLOR

Type: Boolean Default: (none) Description: Disable colorized log output. Respects the NO_COLOR standard.

When set (to any value), disables ANSI color codes in log output even when running in a terminal. Useful for piping output, screen readers, or personal preference.

Color Scheme (when colors enabled):

  • DEBUG: Cyan - Verbose diagnostic information

  • INFO: Green - Normal operation messages

  • WARNING: Yellow - Warning messages requiring attention

  • ERROR: Red - Error messages

  • CRITICAL: Red with white background - Critical failures

Automatic Detection:

Colors are automatically disabled when:

  • Output is redirected to a file or pipe (not a TTY)

  • NO_COLOR environment variable is set

  • TERM=dumb terminal type

  • JSON output format is enabled

Example:

# Disable colors (NO_COLOR standard)
NO_COLOR=1 nhl-scrabble analyze -v

# Colors enabled in terminal (default)
nhl-scrabble analyze -v

# No colors when piped (automatic)
nhl-scrabble analyze -v > output.log

# View colored output with less
nhl-scrabble analyze -v | less -R  # Requires colors enabled

TERM

Type: String Default: (system-defined) Description: Terminal type. When set to dumb, disables colorized output.

This is a standard POSIX environment variable that indicates terminal capabilities. NHL Scrabble respects TERM=dumb to disable colors for terminals that don’t support ANSI codes.

Note: This is a system-wide variable, not specific to NHL Scrabble.

Example:

# Disable colors for dumb terminal
TERM=dumb nhl-scrabble analyze -v

# Default terminal with colors
TERM=xterm-256color nhl-scrabble analyze -v

Web Server Configuration

NHL_SCRABBLE_WEB_HOST

Type: String Default: 127.0.0.1 Description: Host address for web server. Use 0.0.0.0 to bind to all interfaces.

Security Note: Only use 0.0.0.0 behind a reverse proxy (nginx, Caddy) with proper firewall rules.

Example:

# Development (local only)
export NHL_SCRABBLE_WEB_HOST=127.0.0.1

# Production (behind reverse proxy)
export NHL_SCRABBLE_WEB_HOST=0.0.0.0

NHL_SCRABBLE_WEB_PORT

Type: Integer Default: 8000 Description: Port for web server to listen on.

Example:

export NHL_SCRABBLE_WEB_PORT=5000

NHL_SCRABBLE_WEB_WORKERS

Type: Integer Default: 4 Description: Number of Gunicorn worker processes for production.

Recommended Formula: (2 * CPU_COUNT) + 1

Example:

# 2 CPU cores → 5 workers
export NHL_SCRABBLE_WEB_WORKERS=5

# 4 CPU cores → 9 workers
export NHL_SCRABBLE_WEB_WORKERS=9

NHL_SCRABBLE_CORS_ORIGINS

Type: String (comma-separated URLs) Default: http://localhost:8000,http://127.0.0.1:8000 Description: Allowed CORS origins for cross-origin requests.

Security Note: In production, only list your actual domain(s).

Example:

# Development
export NHL_SCRABBLE_CORS_ORIGINS="http://localhost:8000,http://localhost:3000"

# Production
export NHL_SCRABBLE_CORS_ORIGINS="https://yourdomain.com,https://www.yourdomain.com"

# Multiple domains
export NHL_SCRABBLE_CORS_ORIGINS="https://app.example.com,https://api.example.com"

NHL_SCRABBLE_CACHE_TTL

Type: Integer Default: 3600 Description: Time-to-live for web interface analysis cache (in seconds).

Note: This is separate from NHL API cache (NHL_SCRABBLE_CACHE_EXPIRY). Web cache stores complete analysis results.

Example:

# 30 minutes
export NHL_SCRABBLE_CACHE_TTL=1800

# 2 hours
export NHL_SCRABBLE_CACHE_TTL=7200

# Disable web caching (always fetch fresh)
export NHL_SCRABBLE_CACHE_TTL=0

Setting Variables

Temporary (current shell)

export NHL_SCRABBLE_API_TIMEOUT=30
nhl-scrabble analyze

Persistent (shell profile)

Add to ~/.bashrc or ~/.zshrc:

export NHL_SCRABBLE_API_TIMEOUT=30
export NHL_SCRABBLE_OUTPUT_FORMAT=json

Via .env file

Create .env in project directory:

NHL_SCRABBLE_API_TIMEOUT=30
NHL_SCRABBLE_OUTPUT_FORMAT=json