today - Today's Liturgical Information

Display liturgical color, celebration, readings, saints, and rosary mysteries.

Usage:

catholic-liturgy-tool today [OPTIONS]

Options:

• --json - Output JSON (pipe to jq for processing)
• --full-text, -t - Include full scripture texts
• --detail, -d - Include explanations for colors, seasons, ranks
• --no-cache - Bypass cache, fetch fresh data
• --no-color - Disable ANSI color codes
• -v/-vv/-vvv - Verbosity (INFO/DEBUG/TRACE)

Examples:

catholic-liturgy-tool today              # Human-readable output
catholic-liturgy-tool today --json       # JSON for scripting
catholic-liturgy-tool today -t           # Include full texts
catholic-liturgy-tool today --json | jq '.readings'

date - Specific Date Lookup

Display liturgical information for a specific date.

Usage:

catholic-liturgy-tool date DATE [OPTIONS]

Arguments:

• DATE - ISO format date (YYYY-MM-DD)

Examples:

catholic-liturgy-tool date 2025-12-25    # Christmas
catholic-liturgy-tool date 2025-04-20    # Easter
catholic-liturgy-tool date 2025-11-01 --json | jq '.celebration'

ccc - Catechism Lookup

Look up Catechism of the Catholic Church paragraphs by number, range, or keyword.

Usage:

catholic-liturgy-tool ccc [REFERENCE] [OPTIONS]

Arguments/Options:

• REFERENCE - Paragraph number (2559) or range (2559-2561)
• --search, -s - Search keyword in CCC text
• --limit, -l - Max search results [default: 10]
• --json - Output JSON

Examples:

catholic-liturgy-tool ccc 2559           # Single paragraph
catholic-liturgy-tool ccc 2559-2565      # Paragraph range
catholic-liturgy-tool ccc -s "prayer"    # Search for keyword
catholic-liturgy-tool ccc -s "trinity" --json | jq '.[0].text'

rosary - Rosary Prayers and Mysteries

Show complete rosary guide with prayers and mysteries.

Usage:

catholic-liturgy-tool rosary [OPTIONS]

Options:

• --day - Weekday: monday|tuesday|...|sunday
• --mystery, -m - Mystery: joyful|sorrowful|glorious|luminous
• --prayers, -p - Show prayers only, omit mysteries
• --json - Output JSON

Examples:

catholic-liturgy-tool rosary                # Today's mysteries
catholic-liturgy-tool rosary --day monday   # Joyful (Monday)
catholic-liturgy-tool rosary -m sorrowful   # Sorrowful mysteries
catholic-liturgy-tool rosary -p             # Prayers only
catholic-liturgy-tool rosary --json | jq '.mysteries'

Multi-Level Verbosity Logging

Control logging detail with progressive verbosity levels. Logs output to stderr.

Examples:

catholic-liturgy-tool today -v     # INFO level
catholic-liturgy-tool today -vv    # DEBUG level
catholic-liturgy-tool today -vvv   # TRACE level

Shell Completion

Native shell completion for bash, zsh, and fish.

Installation:

# Bash (add to ~/.bashrc)
eval "$(catholic-liturgy-tool completion generate bash)"

# Zsh (add to ~/.zshrc)
eval "$(catholic-liturgy-tool completion generate zsh)"

# Fish
catholic-liturgy-tool completion generate fish > \
    ~/.config/fish/completions/catholic-liturgy-tool.fish

Pipeline Composition

Compose commands with Unix pipes for workflows.

Examples:

# Extract liturgical color
catholic-liturgy-tool today --json | jq -r '.celebration.color'

# Get gospel reference
catholic-liturgy-tool today --json | jq -r '.readings.gospel'

# List all CCC paragraphs about prayer
catholic-liturgy-tool ccc -s "prayer" --json | jq '.[].number'

# Get first mystery name
catholic-liturgy-tool rosary --json | jq '.mysteries[0].title'

Common Issues

Issue: Command not found

# Verify installation
catholic-liturgy-tool --version

# Reinstall if needed
cd catholic-liturgy-tool
uv tool install . --reinstall

Issue: Cache stale data

# Bypass cache
catholic-liturgy-tool today --no-cache

Issue: API errors

# Enable verbose logging to see details
catholic-liturgy-tool today -vv

Getting Help

# Show help
catholic-liturgy-tool --help

# Command-specific help
catholic-liturgy-tool today --help
catholic-liturgy-tool ccc --help
catholic-liturgy-tool rosary --help