📖 USCCB CLI

Command-line tool for accessing daily Catholic Mass readings and prayers from the United States Conference of Catholic Bishops (USCCB).

🙏 Overview

This skill provides scrapers that interact with the USCCB website to retrieve:

• ⛪ Mass Times: Find nearby Catholic churches with Mass schedules and contact information
• 📖 Daily Bible Readings: Complete Mass readings including First Reading, Psalm, Gospel, etc.
• 🙏 Prayers: Search and retrieve Catholic prayers and devotions in English or Spanish

All tools output markdown by default for easy LLM parsing, with optional --json flag for structured data output.

🛠️ Installation

Requirements

• Python 3.6+
• pip

Setup

cd ~/.openclaw/skills/usccb_cli
pip install -r requirements.txt
chmod +x usccbcli  # Make CLI executable

📚 Usage Examples

⛪ Mass Times

Find Catholic churches near a location with Mass schedules and contact information.

Find churches near a city:

./usccbcli mass-times "Boston, MA"

Find churches with pagination:

./usccbcli mass-times "New York, NY" --page 2

Limit number of results:

./usccbcli mass-times "Chicago, IL" --limit 5

Get JSON output instead of markdown:

./usccbcli mass-times "Boston, MA" --json

Output (Markdown - Default):

# Catholic Churches Near Boston, MA
**Coordinates:** 42.3601, -71.0589
**Results:** 2 churches (Page 1)

## 1. The Paulist Center
**Address:** 5 Park Street
**Location:** Boston, Massachusetts 02108
**Phone:** (617) 742-4460
**Website:** http://www.paulistcenter.org
**Distance:** 0.27 miles

**Mass Times:**
- **Sunday:** 10:00, 18:00
- **Monday:** 12:00
- **Tuesday:** 12:00
- **Wednesday:** 12:00
- **Thursday:** 12:00
- **Friday:** 11:00 (Confessions), 12:00
- **Saturday:** 17:00

---

Output (JSON with --json flag):

{
  "location_searched": "Boston, MA",
  "coordinates": {
    "latitude": 42.3601,
    "longitude": -71.0589
  },
  "page": 1,
  "total_results": 2,
  "churches": [
    {
      "name": "The Paulist Center",
      "distance": "0.27",
      "church_address_street_address": "5 Park Street",
      "church_address_city_name": "Boston",
      "church_address_providence_name": "Massachusetts",
      "church_address_postal_code": "02108",
      "phone_number": "(617) 742-4460",
      "url": "http://www.paulistcenter.org",
      "church_worship_times": [...]
    }
  ]
}

Arguments:

• location: Required. City, address, or ZIP code to search near
• --page N: Optional. Page number for pagination (default: 1)
• --limit N: Optional. Maximum number of churches to return
• --json: Optional. Output JSON instead of markdown (default: markdown)

Data Source: Mass times data comes from masstimes.org via the updateparishdata.org API - the same data source used by the popular MassTimes.org website trusted by millions of Catholics worldwide.

Note: Churches are sorted by distance from the searched location. Outputs markdown by default for easy LLM parsing. Use --json for structured data. The API uses OpenStreetMap's Nominatim service for geocoding (no API key required).

---

📖 Daily Bible Readings

Get the complete daily Mass readings for any date.

Get today's readings:

./usccbcli readings

Get readings for a specific date:

./usccbcli readings --date 2026-12-25

Filter for specific readings only:

./usccbcli readings --titles "Gospel" "Reading 1"

Get JSON output instead of markdown:

./usccbcli readings --date 2026-12-25 --json

Output (Markdown - Default):

# Daily Mass Readings - The Nativity of the Lord (Christmas) - Mass During the Day
**Date:** 2026-12-25
**Source:** https://bible.usccb.org/bible/readings/122526.cfm

## Reading 1
**Citation:** Is 52:7-10

How beautiful upon the mountains
are the feet of him who brings glad tidings,
Announcing peace, bearing good news...

---

## Gospel
**Citation:** Jn 1:1-18

In the beginning was the Word,
and the Word was with God,
and the Word was God...

---

Output (JSON with --json flag):

{
  "date": "2026-12-25",
  "url": "https://bible.usccb.org/bible/readings/122526.cfm",
  "liturgical_date": "The Nativity of the Lord (Christmas) - Mass During the Day",
  "readings": [
    {
      "title": "Reading 1",
      "citation": "Is 52:7-10",
      "text": "How beautiful upon the mountains are the feet of him who brings glad tidings..."
    },
    {
      "title": "Gospel",
      "citation": "Jn 1:1-18",
      "text": "In the beginning was the Word, and the Word was with God, and the Word was God..."
    }
  ]
}

Arguments:

• --date YYYY-MM-DD: Optional. Get readings for specific date (defaults to today)
• --titles "Title1" "Title2" ...: Optional. Filter to return only specific readings
• --json: Optional. Output JSON instead of markdown (default: markdown)

---

🙏 Search Prayers

Search for Catholic prayers and devotions.

Search for prayers in English (default):

./usccbcli search-prayers "Hail Mary"

Search for prayers in Spanish:

./usccbcli search-prayers "Ave María" --language es

Limit search results:

./usccbcli search-prayers "peace" --limit 10

Filter by prayer type or committee:

./usccbcli search-prayers "Advent" --type "Seasonal Prayer"

Get JSON output instead of markdown:

./usccbcli search-prayers "peace" --json

Output (Markdown - Default):

# Prayer Search Results for: "peace"
**Total Results:** 3
**Source:** https://www.usccb.org/prayers?key=peace

## 1. Pope Francis' Prayer for Peace
**Type:** Papal Prayers
**URL:** https://www.usccb.org/prayers/pope-francis-prayer-peace

## 2. Prayer for Peace
**Type:** Prayers for the Church and the World
**URL:** https://www.usccb.org/prayers/prayer-peace

---

Output (JSON with --json flag):

{
  "query": "peace",
  "search_url": "https://www.usccb.org/prayers?key=peace",
  "total_results": 3,
  "prayers": [
    {
      "title": "Pope Francis' Prayer for Peace",
      "url": "https://www.usccb.org/prayers/pope-francis-prayer-peace",
      "type": "Papal Prayers"
    },
    {
      "title": "Prayer for Peace",
      "url": "https://www.usccb.org/prayers/prayer-peace",
      "type": "Prayers for the Church and the World"
    }
  ]
}

Arguments:

• query: Required. Search term for prayers
• --language {en,es}: Optional. Language filter - 'en' for English, 'es' for Spanish (default: en)
• --limit N: Optional. Maximum number of results (valid values: 20, 50, or 100, default: 20)
• --type "Type": Optional. Filter by prayer type
• --office "Office": Optional. Filter by USCCB office/committee
• --json: Optional. Output JSON instead of markdown (default: markdown)

Note: Due to USCCB API limitations, --limit only accepts values of 20, 50, or 100. Other values will be rounded to the nearest valid option.

---

📿 Get Prayer Text

Retrieve the full text of a specific prayer.

Get a prayer by URL:

./usccbcli get-prayer "https://www.usccb.org/prayers/hail-mary"

Get JSON output instead of markdown:

./usccbcli get-prayer "https://www.usccb.org/prayers/hail-mary" --json

Output (Markdown - Default):

# Hail Mary
**Source:** https://www.usccb.org/prayers/hail-mary

---

Hail, Mary, full of grace,
the Lord is with thee.
Blessed art thou among women
and blessed is the fruit of thy womb, Jesus.
Holy Mary, Mother of God,
pray for us sinners,
now and at the hour of our death.

Amen.

---

Output (JSON with --json flag):

{
  "title": "Hail Mary",
  "url": "https://www.usccb.org/prayers/hail-mary",
  "text": "Hail, Mary, full of grace,\nthe Lord is with thee.\nBlessed art thou among women\nand blessed is the fruit of thy womb, Jesus.\nHoly Mary, Mother of God,\npray for us sinners,\nnow and at the hour of our death.\n\nAmen."
}

Arguments:

• url: Required. Full URL to the prayer page on USCCB.org
• --json: Optional. Output JSON instead of markdown (default: markdown)

---

🛒 Typical Workflows

📖 Daily Scripture Reading

• Get today's readings: ./usccbcli readings
• Get Gospel only: ./usccbcli readings --titles "Gospel"
• Parse the readings array to extract text
• Present formatted readings to user

⛪ Finding a Church

• Search by location: ./usccbcli mass-times "Boston, MA"
• Limit results: ./usccbcli mass-times "Boston, MA" --limit 5
• Extract church names, addresses, phone numbers
• Display Mass times and contact info

🙏 Prayer Discovery

• Search in English: ./usccbcli search-prayers "peace"
• Search in Spanish: ./usccbcli search-prayers "paz" --language es
• Get full text: ./usccbcli get-prayer "https://www.usccb.org/prayers/hail-mary"
• Present prayer text for devotion

📅 Weekly Planning

• Loop through dates to get readings for the week
• Extract Gospel citations for quick reference
• Plan scripture study or homily preparation

---

💻 Output Format

All commands:

• Output markdown by default to stdout (easy for LLMs to parse)
• Optional --json flag for structured JSON output
• Send errors to stderr
• Exit with code 1 on errors
• No debug output - only clean markdown/JSON or error messages

Why Markdown Default?

• LLMs parse markdown more efficiently than nested JSON for Q&A tasks
• Headers (# ##) and bold labels (Field:) provide clear structure
• Bullet lists and tables are token-efficient
• Use --json when you need programmatic data access

This makes them perfect for:

• LLM/AI agent integration (markdown)
• Shell scripts and automation (JSON)
• Catholic app development (JSON)
• Direct human reading (markdown)

---

⚠️ Error Handling

Network Issues:

$ ./usccbcli readings
Error: Failed to fetch readings: Connection timeout

Invalid Date:

$ ./usccbcli readings --date 2026-13-45
Error: Invalid date format: 2026-13-45. Use YYYY-MM-DD

Location Not Found:

$ ./usccbcli mass-times "NonexistentCity12345"
Error: Could not geocode location: NonexistentCity12345

Invalid Prayer URL:

$ ./usccbcli get-prayer "https://invalid-url.com"
Error: Failed to fetch prayer content

All errors are sent to stderr and commands exit with code 1.

---

🤖 Integration with OpenClaw

These tools are designed as an OpenClaw skill. See SKILL.md for LLM integration details including:

• Tool calling parameters for all commands
• Example prompts for readings, Mass times, and prayers
• Response formatting guidelines
• Multi-language support details

---

🧪 Testing

Run the test suite:

./run_tests.sh

Run with coverage:

pytest --cov=lib tests/

See tests/README.md for more information.

---

🌿 Contributing

When modifying the tools:

• Maintain JSON output format for backward compatibility
• Send all errors to stderr
• Exit with code 1 on failures
• Update both SKILL.md and README.md with changes
• Test with real API calls to verify output
• Add unit tests for new functionality

---

📜 License

MIT License - See LICENSE file for details.

This project scrapes publicly available content from USCCB.org. Please respect their terms of service and use responsibly.

---

🔗 Resources

• USCCB Daily Readings
• USCCB Prayers
• USCCB Website
• MassTimes.org - Mass times data source
• Scripture texts are from the New American Bible, revised edition © 2010, 1991, 1986, 1970 Confraternity of Christian Doctrine, Washington, D.C.

---

📋 Command Reference

Command	Description	Required Args	Optional Args
readings	Get daily Mass readings	None	--date, --titles, --json
mass-times	Find nearby churches	location	--page, --limit, --json
search-prayers	Search for prayers	query	--language, --limit, --type, --office, --json
get-prayer	Get full prayer text	url	--json

---

⚖️ Disclaimer

This project is not affiliated with or endorsed by the United States Conference of Catholic Bishops (USCCB). It is an independent tool created by a Catholic nerd who uses OpenClaw to access publicly available USCCB resources. All content is sourced from the official USCCB website and remains their intellectual property. Please use this tool respectfully and in accordance with USCCB's terms of service.

---

✝️ Christ is King ✝️