🌙 Romdhan

A Modern CLI Companion for the Blessed Month of Ramadan

✨ Overview

Romdhan is a meticulously crafted CLI tool designed for developers, terminal enthusiasts, and anyone who values efficiency. Built with TypeScript and modern Node.js practices, it brings the essential tools of Ramadan directly to your terminal—no GUI needed, no distractions, just pure productivity.

Whether you're checking prayer times between code deployments, reading Quran during breaks, or calculating your Zakat obligations, Romdhan delivers a seamless, keyboard-driven experience that respects your workflow.

Why Terminal-Based?

• ⚡ Speed: No loading screens, no bloated UIs—just instant results
• 🎯 Focus: Stay in your development flow without context switching
• 🌍 Universal: Works on any platform with a terminal (macOS, Linux, Windows)
• 🔧 Scriptable: Integrate with your automation workflows and cron jobs
• 💾 Lightweight: Minimal resource footprint compared to GUI applications

📦 Installation

Global Installation (Recommended)

npm install -g romdhan

Using npx (Zero Installation)

npx romdhan --help

System Requirements

• Node.js: >= 16.0.0 (LTS recommended)
• Terminal: Unicode support for optimal display (iTerm2, Windows Terminal, GNOME Terminal, etc.)

Verify Installation

romdhan --version
# Output: 1.0.3

🚀 Quick Start

Get up and running in under 60 seconds:

# Step 1: Configure your location (one-time setup)
romdhan settings

# Step 2: Check today's prayer times
romdhan prayer

# Step 3: View Ramadan countdown
romdhan countdown

# Step 4: Read Surah Al-Fatiha
romdhan quran

# Step 5: Get daily inspiration
romdhan info

🎯 Features

🕌 Accurate Prayer Times

Powered by the Aladhan API, Romdhan provides precise prayer times for any city worldwide with 15 different calculation methods to match your region's conventions.

Supported Methods:

| Method ID | Name | Recommended Region | | --------- | --------------------------------------------- | ----------------------- | | 1 | University of Islamic Sciences, Karachi | South Asia | | 2 | Islamic Society of North America (ISNA) | North America | | 3 | Muslim World League | Europe, Far East | | 4 | Umm al-Qura University, Makkah | Arabian Peninsula | | 5 | Egyptian General Authority of Survey | Egypt, Africa | | 6 | Institute of Geophysics, University of Tehran | Iran, Shia | | 7 | Gulf Region | UAE, Qatar, Bahrain | | 8 | Kuwait | Kuwait | | 9 | Qatar | Qatar | | 10 | Majlis Ugama Islam Singapura | Singapore, Malaysia | | 11 | Union Organization Islamic de France | France | | 12 | Diyanet İşleri Başkanlığı, Turkey | Turkey | | 13 | Spiritual Administration of Muslims of Russia | Russia | | 14 | Moonsighting Committee | Global (sighting-based) | | 15 | Dubai (experimental) | Dubai |

⏰ Intelligent Ramadan Tracking

Automatically detects your location's Ramadan start date based on moon sighting data. For countries with specific sightings (like Tunisia starting Feb 19, 2026), Romdhan applies country-specific overrides.

Smart States:

• Pre-Ramadan: Countdown to first day
• During Ramadan: Current day with progress visualization
• Post-Ramadan: Countdown to next year's Ramadan

📖 Quran Reader with Proper Arabic Rendering

Access all 114 Surahs with:

• Uthmani script with proper Arabic ligatures
• English translations (Asad interpretation)
• RTL text direction for authentic Arabic display
• Pagination to read at your own pace

📝 Curated Hadith Collection

Authentic Ramadan-related hadiths featuring:

• Transliteration for terminal compatibility
• Verified English translations
• Proper attribution (Sahih Bukhari, Muslim, etc.)
• Arabic text support for capable terminals

💰 Interactive Zakat Calculator

A guided wealth assessment that computes:

• Cash and bank account balances
• Gold and silver valuations
• Investment portfolios
• Outstanding debts
• Nisab threshold comparison (87.48g gold / 612.36g silver)
• Final Zakat obligation (2.5% of qualifying wealth)

📿 Digital Tasbih Counter

Interactive dhikr tool with:

• 6 preset dhikr patterns
• Visual progress indication
• Keyboard-driven counting (Enter to increment, Q to quit)
• Session completion tracking

⚙️ Persistent Configuration

Your preferences are automatically saved:

• Location: City and country for prayer times
• Calculation Method: Your preferred madhab/convention
• Auto-detection: IP-based location detection available

Config Locations:

• macOS: ~/Library/Preferences/romdhan/config.json
• Linux: ~/.config/romdhan/config.json
• Windows: %APPDATA%/romdhan/config.json

📚 Command Reference

romdhan prayer — Prayer Times

# Use saved settings
romdhan prayer

# Override location
romdhan prayer --city "New York" --country "US"
romdhan prayer -c London -C UK

# Specify calculation method
romdhan prayer --method 4

Output Preview:

╔══════════════════════════════════════════════════╗
║  🕌 New York, US                                 ║
╠══════════════════════════════════════════════════╣
║                                                  ║
║  📅 Gregorian:    February 19, 2026              ║
║  🌙 Hijri:        1 Ramadan 1447 AH              ║
║  🌍 Timezone:     America/New_York               ║
║  📐 Method:       ISNA                           ║
║                                                  ║
║  🕐 Prayer Times                                 ║
║  ──────────────────────────────────────────────  ║
║     🌅 Fajr:       05:24 AM                      ║
║     ☀️ Sunrise:    07:12 AM                      ║
║  ▶  🌞 Dhuhr:      12:15 PM  (Next Prayer)       ║
║     🌤️ Asr:        03:45 PM                      ║
║     🌇 Maghrib:    06:18 PM  (Iftar)             ║
║     🌙 Isha:       07:45 PM                      ║
║                                                  ║
╚══════════════════════════════════════════════════╝

romdhan countdown — Ramadan Tracker

romdhan countdown

Three Intelligent Modes:

Before Ramadan:

╔══════════════════════════════════════════════════╗
║  🌙 Countdown to Ramadan                         ║
╠══════════════════════════════════════════════════╣
║                                                  ║
║  📅 Next Ramadan                                 ║
║     February 19, 2026                            ║
║                                                  ║
║  ⏰ 0 days remaining                             ║
║                                                  ║
║  🌟 Start preparing your heart and soul!         ║
║                                                  ║
╚══════════════════════════════════════════════════╝

During Ramadan:

╔══════════════════════════════════════════════════╗
║  ✨ Ramadan Progress                             ║
╠══════════════════════════════════════════════════╣
║                                                  ║
║  🌙 Ramadan Mubarak!                             ║
║                                                  ║
║  Day 1 of 30                                     ║
║                                                  ║
║  Progress:                                       ║
║  ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  3%     ║
║                                                  ║
║  🎉 29 days until Eid al-Fitr!                   ║
║                                                  ║
╚══════════════════════════════════════════════════╝

romdhan quran — Quran Reader

# Surah Al-Fatiha (default)
romdhan quran

# Specific Surah
romdhan quran --surah 36
romdhan quran -s 67

# Limit ayahs (useful for long Surahs)
romdhan quran --surah 2 --limit 10
romdhan quran -s 2 -l 10

Recommended Surahs:

• 1 — Al-Fatiha (recited in every rak'ah)
• 18 — Al-Kahf (recommended every Friday)
• 36 — Yaseen (Heart of the Quran)
• 55 — Ar-Rahman (blessings of Allah)
• 67 — Al-Mulk (protection from grave punishment)
• 112 — Al-Ikhlas (Tawhid)

romdhan hadith — Daily Hadith

# Standard output (transliteration)
romdhan hadith

# Arabic text (if terminal supports)
romdhan hadith --arabic

romdhan zakat — Zakat Calculator

romdhan zakat

Interactive prompts guide you through:

1. Cash on hand
2. Bank account balances
3. Gold jewelry (grams)
4. Silver items (grams)
5. Investment values
6. Outstanding debts

Automatic Calculations:

• Total zakatable wealth
• Nisab threshold check
• Final Zakat amount (2.5%)

romdhan tasbih — Digital Counter

# Default dhikr
romdhan tasbih

# Specific dhikr
romdhan tasbih --dhikr "SubhanAllah"
romdhan tasbih -d "Alhamdulillah"

Available Options:

• SubhanAllah — 33x
• Alhamdulillah — 33x
• Allahu Akbar — 34x
• La ilaha illallah — 100x
• Astaghfirullah — 100x
• Allahumma salli ala Muhammad — 100x

Controls:

• Enter — Count +1
• Q + Enter — Quit

romdhan settings — Configuration

romdhan settings

Interactive Menu:

1. 📍 Set City & Country
2. 🌍 Auto-detect Location (via IP)
3. 📐 Change Calculation Method
4. 👁️ View Current Settings
5. 🗑️ Reset to Defaults

romdhan info — Daily Inspiration

romdhan info
romdhan info --tips  # Show additional tips

Output includes:

• Ramadan status/countdown
• Current moon phase
• Motivational Islamic quote
• Daily Ramadan tip

🛠️ Development

Prerequisites

• Node.js 16.x or higher
• npm 8.x or higher
• Git

Local Setup

# Clone repository
git clone https://github.com/TheNeovimmer/romdhan.git
cd romdhan

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Run specific command in dev
npm run dev -- prayer --city Tunis --country TN

Available Scripts

npm run build       # Compile TypeScript to dist/
npm run dev         # Run with ts-node (development)
npm start           # Run compiled version
npm run lint        # Run ESLint
npm run lint:fix    # Fix ESLint issues
npm run format      # Format with Prettier
npm run clean       # Remove dist/ directory
npm run prepublish  # Clean + build before publishing

Project Structure

romdhan/
├── src/
│   ├── api/           # External API integrations
│   │   ├── aladhan.ts      # Prayer times & Hijri dates
│   │   ├── quran.ts        # Quran Cloud API
│   │   ├── hadith.ts       # Hadith database
│   │   └── location.ts     # IP geolocation
│   ├── commands/      # CLI command implementations
│   │   ├── prayer.ts
│   │   ├── quran.ts
│   │   ├── countdown.ts
│   │   ├── zakat.ts
│   │   ├── tasbih.ts
│   │   ├── hadith.ts
│   │   ├── info.ts
│   │   └── settings.ts
│   ├── utils/         # Utility functions
│   │   ├── display.ts      # Terminal UI helpers
│   │   ├── config.ts       # Settings management
│   │   ├── moon.ts         # Moon phase calculations
│   │   └── quotes.ts       # Inspirational quotes
│   └── index.ts       # CLI entry point
├── dist/              # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

🔄 Changelog

v1.0.3 (2026-02-19)

🌐 New Website:

• Official Website: Launched https://romdhan.vercel.app with interactive documentation
• Live Demo: Try commands directly in the browser with the interactive terminal
• Bilingual Support: Full English and Arabic language support
• Dark/Light Mode: Toggle between themes for comfortable viewing
• Modern UI: Built with React, TypeScript, Tailwind CSS, and GSAP animations

✨ Improvements:

• Updated README with website badge and links
• Added homepage URL to package.json

v1.0.2 (2026-02-19)

🚀 New Features:

• Dynamic Ramadan Date Fetching: Automatically fetches Ramadan dates from Aladhan API based on your location
• Country-Specific Overrides: Supports moon sighting variations by country (e.g., Tunisia starts Feb 19, 2026)
• Improved Arabic Text Rendering: Added RTL markers for proper Arabic display in terminals

✨ Improvements:

• Enhanced Quran reader with better Arabic ligature support
• Settings now properly propagate to all commands
• More accurate Ramadan day calculation based on user country

🔧 Technical:

• Refactored fetchRamadanDate() to use Hijri-to-Gregorian API conversion
• Updated getRamadanDay() to accept country parameter
• Added country override system for moon sighting differences

v1.0.1 (2026-02-18)

✨ Improvements:

• Updated Ramadan 2026 dates
• Fixed display formatting issues
• Performance optimizations

v1.0.0 (2026-02-18)

🎉 Initial Release:

• Prayer times with 15 calculation methods
• Quran reader with translations
• Hadith collection
• Zakat calculator
• Digital tasbih
• Ramadan countdown
• Daily inspiration
• Settings management

🤝 Contributing

We welcome contributions from the community! Please follow these guidelines:

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/romdhan.git
3. Create a feature branch: git checkout -b feature/your-feature-name
4. Make your changes
5. Test thoroughly: npm run build && npm start
6. Commit with conventional messages (see below)
7. Push to your fork: git push origin feature/your-feature-name
8. Open a Pull Request

Commit Convention

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat: — New feature
• fix: — Bug fix
• docs: — Documentation changes
• style: — Code style (formatting, no logic change)
• refactor: — Code refactoring
• perf: — Performance improvements
• test: — Adding or updating tests
• chore: — Build process or auxiliary tool changes

Examples:

git commit -m "feat(prayer): add support for method 16"
git commit -m "fix(quran): resolve Arabic text rendering issue"
git commit -m "docs(readme): update installation instructions"
git commit -m "refactor(api): optimize Aladhan API calls"

Code Standards

• TypeScript: Strict mode enabled
• ESLint: Airbnb configuration
• Prettier: 2-space indentation, single quotes
• Tests: Write tests for new features

🙏 Acknowledgments

API Providers

This project wouldn't be possible without these excellent services:

• Aladhan API — Prayer times, Hijri calendar, and Islamic date conversions
• Al Quran Cloud — Comprehensive Quran API with multiple editions
• IP-API — Free IP geolocation service

Open Source Dependencies

• Commander.js — CLI framework
• Chalk — Terminal styling
• Boxen — Terminal boxes
• Ora — Loading spinners
• Inquirer.js — Interactive prompts
• Day.js — Date manipulation

📄 License

MIT License — see LICENSE file for details.

MIT License

Copyright (c) 2026 Ilyes Bouzayen

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

💬 Support

Getting Help

• Documentation: Start with romdhan --help
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Common Issues

Q: Prayer times seem incorrect for my location A: Run romdhan settings and verify your city/country. Also check that you've selected the appropriate calculation method for your region.

Q: Arabic text doesn't display correctly A: Ensure your terminal supports Unicode/UTF-8. Recommended terminals: iTerm2 (macOS), Windows Terminal (Windows), GNOME Terminal/Konsole (Linux).

Q: How do I change the calculation method? A: Run romdhan settings → "Change Calculation Method" and select from the list.

🌙 Ramadan Mubarak! 🌙

May Allah accept your fasts, prayers, and good deeds

May this Ramadan bring you peace, blessings, and spiritual growth