hadith-collections/CLI_README.md

A comprehensive npm package for searching and browsing hadith collections with Arabic and English support

# Hadith Collections CLI Tool

A single-file command-line interface for navigating hadith collections, books, chapters, and viewing individual hadiths in the terminal.

## Features

🌙 **Hierarchical Navigation**: Collections → Books → Chapters → Hadiths
🔍 **Autocomplete Search**: Type-ahead search for easy navigation
📚 **16 Collections**: Including Sahih al-Bukhari, Sahih Muslim, and more
🌐 **Bilingual Support**: Arabic text with English translations when available
🎲 **Random Hadith**: Get random hadiths for daily reading
⚡ **Fast Navigation**: Quick back navigation between levels
📜 **Rich Display**: Formatted hadith display with narrator information

## Usage

### Running the CLI

```bash
# Run directly
node cli.js

# Or if installed globally
hadith-cli
```

### Navigation Flow

1. **Select Collection**: Choose from 16 available hadith collections
   - Use arrow keys or type to search
   - Collections include: Sahih al-Bukhari, Sahih Muslim, Sunan an-Nasa'i, etc.

2. **Select Book**: Browse books within the selected collection
   - Each collection has multiple books organized by topic
   - Example: "Book 1: Revelation", "Book 2: Belief", etc.

3. **Select Chapter**: View chapters within the selected book
   - Chapters break down books into specific topics
   - Option to view all hadiths in a book directly

4. **Select Hadith**: Choose individual hadiths to read
   - Preview shows first 100 characters
   - Option for random hadith selection

5. **View Hadith**: Full display with:
   - Arabic text
   - English translation (when available)
   - Narrator information
   - Reference (URN)
   - Comments and grades (when available)

### Navigation Controls

- **Type to search**: Filter options by typing
- **Arrow keys**: Navigate through options
- **Enter**: Select option
- **← Back**: Return to previous level
- **Ctrl+C**: Exit the application

### Example Navigation Path

```
Collections
├── Sahih al-Bukhari (صحيح البخاري)
    ├── Book 1: Revelation (كتاب بدء الوحى)
        ├── Chapter 1: How the Divine Inspiration started...
            ├── Hadith 1: Narrated 'Umar bin Al-Khattab...
            ├── Hadith 2: Narrated 'Aisha...
            └── ...
        └── ...
    └── ...
```

## Available Collections

The CLI provides access to these major hadith collections:

1. **Sahih al-Bukhari** (صحيح البخاري) - 97 books
2. **Sahih Muslim** (صحيح مسلم)
3. **Sunan an-Nasa'i** (سنن النسائي)
4. **Sunan Abi Dawud** (سنن أبي داود)
5. **Jami` at-Tirmidhi** (جامع الترمذي)
6. **Sunan Ibn Majah** (سنن ابن ماجه)
7. **Muwatta Malik** (موطأ مالك)
8. **Musnad Ahmad** (مسند أحمد)
9. **An-Nawawi's 40 Hadith** (الأربعون النووية)
10. **Collections of Forty** (الأربعينات)
11. **Riyad as-Salihin** (رياض الصالحين)
12. **Mishkat al-Masabih** (مشكاة المصابيح)
13. **Al-Adab Al-Mufrad** (الأدب المفرد)
14. **Ash-Shama'il Al-Muhammadiyah** (الشمائل المحمدية)
15. **Bulugh al-Maram** (بلوغ المرام)
16. **Hisn al-Muslim** (حصن المسلم)

## Installation as Global Command

To use `hadith-cli` globally:

```bash
npm install -g .
hadith-cli
```

## Dependencies

- `inquirer-autocomplete-standalone`: For the interactive CLI interface
- `sqlite3`: For database access (already included in the main package)

## Technical Details

- **Single File**: The entire CLI is contained in `cli.js`
- **Database**: Uses the same SQLite database as the main package
- **Memory Efficient**: Only loads data as needed for navigation
- **Graceful Exit**: Properly closes database connections on exit

## Keyboard Shortcuts

- **Ctrl+C**: Exit application gracefully
- **Enter**: Confirm selection
- **Escape**: Cancel current input
- **Tab**: Autocomplete (when applicable)

## Example Session

```
🌙 Welcome to Hadith Collections CLI
═══════════════════════════════════════

? 📚 Select a hadith collection: Sahih al-Bukhari (صحيح البخاري)

📖 Books in Sahih al-Bukhari:
──────────────────────────────────────

? 📖 Select a book: Book 1: Revelation (كتاب بدء الوحى)

📄 Chapters in Revelation (كتاب بدء الوحى):
──────────────────────────────────────

? 📄 Select a chapter: Chapter 1: How the Divine Inspiration started...

📜 Hadiths in Revelation - How the Divine Inspiration started...:
──────────────────────────────────────

? 📜 Select a hadith to read: Hadith 1: Narrated 'Umar bin Al-Khattab: I heard Allah's Messenger saying...

🕌 HADITH DISPLAY
══════════════════════════════════════════════════════════

📍 URN: 1:1:1:1
📊 Collection ID: 1, Book ID: 1

👤 حدثنا

📜 Arabic Content:
────────────────────────
[Arabic hadith text]

👤 رضي الله عنه

🌍 English Translation:
────────────────────────
Narrated 'Umar bin Al-Khattab: I heard Allah's Messenger saying, "The reward of deeds depends upon the intentions..."

📖 Reference: Book 1, Hadith 1

══════════════════════════════════════════════════════════

Press Enter to continue...
```

---

**May Allah bless your study of the Sunnah! 🤲**