ramadan-cli-pro

v1.3.2

Published

3 months ago

Professional-grade Ramadan prayer times CLI with TUI dashboard, i18n, caching, and notifications

0High
0Medium
0Low

hammadxcm

ramadan prayer-times sehar iftar hijri cli tui dashboard

Features

Prayer Times — Sehar & Iftar times for any city worldwide via the Aladhan API
TUI Dashboard — Interactive React/Ink terminal dashboard with live countdown and Ramadan progress bar
Interactive Settings Editor — Edit all settings directly from the TUI with keyboard navigation, inline dropdowns, text input, and instant toggles
6 Color Themes — ramadan-green, classic-gold, ocean-blue, royal-purple, minimal-mono, high-contrast with live switching in the TUI
Qibla Direction — ASCII compass showing the direction to Makkah from your location
Dua of the Day — 30 daily Ramadan duas with Arabic text, transliteration, and English translation
Quran Verse of the Day — 30 curated verses with Arabic, transliteration, translation, and surah reference
Hadith of the Day — 30 curated hadiths with Arabic, transliteration, translation, source, and narrator
Adhkar Collections — Morning, evening, and post-prayer dhikr with Arabic and transliteration
Prayer Tracking — Mark daily prayers (Fajr, Dhuhr, Asr, Maghrib, Isha, Taraweeh) as complete
Fasting Streaks — Track fasting days with current/longest streak and vacation mode
Badge System — 12 achievements earned automatically based on prayer, fasting, charity, and goals
Ramadan Goals — Set and track personal goals with progress bars
Statistics — Consolidated view of prayer completion, fasting streaks, goals, and badges
Zakat Calculator — Calculate Zakat based on wealth inputs with nisab thresholds
Charity Tracker — Log donations with amounts, descriptions, and categories
City Comparison — Compare prayer times for 2-4 cities side by side
Multi-format Export — Export prayer times as iCal (.ics), CSV, or JSON
Terminal Widget — Compact auto-refreshing display for status bars
Offline Cache — Prefetch 30 days of prayer times for offline use
Hijri Events — Special night annotations (Laylat al-Qadr, last 10 nights)
Location Profiles — Save and switch between multiple named location configurations
82 City Aliases — Short codes like sf, nyc, lhr, dxb, makkah for quick lookups
24 Calculation Methods — Region-specific methods including ISNA, MWL, Umm al-Qura, and more
2 Juristic Schools — Shafi (standard) and Hanafi Asr calculation
12 Languages — English, Arabic, Urdu, Turkish, Malay, Bengali, French, Indonesian, Spanish, German, Hindi, Persian
4 Output Formats — Table, JSON, plain text, and status-line for tmux/polybar
NO_COLOR Support — Respects the NO_COLOR environment variable for accessible plain-text output
Shell Completions — Tab-completion scripts for Bash, Zsh, and Fish
Desktop Notifications — Native OS alerts for Sehar & Iftar via node-notifier
Smart Geolocation — Auto-detect location with 3 fallback geo-IP providers
Persistent Config — Save city, method, school, and timezone preferences with export/import support
File-based Caching — Minimize API calls with intelligent TTL caching
Hijri Dates — Full Hijri calendar alongside Gregorian dates
Custom Roza Date — Override the first day of Ramadan manually
First-Run Setup — Interactive wizard for initial configuration
Update Notifier — Automatic notification when a new version is available on npm
5 CLI Aliases — Run as ramadan-cli-pro, ramadan-pro, ramadan, ramzan, or roza
Zod Validated — Runtime type safety with branded types throughout

Header — Location and Hijri date display with theme colors
PrayerTimesTable — All 5 prayer times with Sehar/Iftar highlights
CountdownTimer — Live countdown to the next prayer event
ProgressBar — Visual progress through the fasting day
StatusBadge — Current fasting status indicator
DuaCard — Dua of the day with Arabic text and translation
QuranVerseCard — Quran verse of the day with surah reference
GoalProgress — Visual goal progress bars
StreakBadge — Fasting streak display with current/longest stats
SettingsEditor — Interactive keyboard-driven settings editor with text input, selection dropdowns, and toggles
ErrorDisplay — Graceful error state rendering
LoadingSpinner — Loading state indicator
Dashboard — Main orchestrator composing all components
Footer — Methodology and attribution info

Quick Start

# Install globally
npm i -g ramadan-cli-pro

# Or with pnpm
pnpm add -g ramadan-cli-pro

# Or run without installing
npx ramadan-cli-pro

# Show today's times (auto-detects your city)
ramadan

# Show times for a specific city
ramadan sf

# Show Qibla direction
ramadan qibla

# Show today's dua
ramadan dua

# Track a prayer
ramadan track fajr

# View your stats
ramadan stats

Tip: You can use any of these aliases: ramadan-cli-pro, ramadan-pro, ramadan, ramzan, or roza.

Usage

Root Command

ramadan [city] [options]

| Flag | Description | |------|-------------| | -c, --city <city> | City name or alias | | -a, --all | Show complete Ramadan month | | -n, --number <n> | Show a specific roza day (1-30) | | -p, --plain | Plain text output | | -j, --json | JSON output | | -s, --status | Status-line output (for status bars) | | -t, --tui | Launch TUI dashboard | | -l, --locale <locale> | Language: en, ar, ur, tr, ms, bn, fr, id, es, de, hi, fa | | --theme <name> | Color theme: ramadan-green, classic-gold, ocean-blue, royal-purple, minimal-mono, high-contrast | | --first-roza-date <YYYY-MM-DD> | Set custom first roza date | | --clear-first-roza-date | Clear custom first roza date | | -v, --version | Show version |

Examples:

# Today's Sehar & Iftar
ramadan

# Full Ramadan schedule
ramadan --all

# Specific roza day
ramadan --number 15

# JSON output
ramadan --json

# Status-line for tmux/polybar
ramadan --status

# Launch TUI dashboard
ramadan --tui

# Arabic locale
ramadan --locale ar

# Bengali locale
ramadan --locale bn

Config

ramadan config [options]

| Flag | Description | |------|-------------| | --city <city> | Save default city | | --country <country> | Save default country | | --method <id> | Calculation method (0-23) | | --school <id> | Juristic school (0=Shafi, 1=Hanafi) | | --latitude <lat> | Save latitude (-90 to 90) | | --longitude <lon> | Save longitude (-180 to 180) | | --timezone <tz> | Save timezone (e.g., America/Los_Angeles) | | --show | Show current configuration | | --clear | Clear all saved configuration | | --export | Export configuration as JSON to stdout | | --import <file> | Import configuration from a JSON file |

Examples:

# Save city and country
ramadan config --city "San Francisco" --country US

# Save calculation method and school
ramadan config --method 2 --school 1

# Save exact coordinates and timezone
ramadan config --latitude 37.7749 --longitude -122.4194 --timezone America/Los_Angeles

# Show current config
ramadan config --show

# Export config to a file
ramadan config --export > my-config.json

# Import config from a file
ramadan config --import my-config.json

# Clear all config
ramadan config --clear

Notify

ramadan notify [options]

| Flag | Description | |------|-------------| | --enable | Enable notifications | | --disable | Disable notifications | | --sehar | Toggle Sehar reminder | | --iftar | Toggle Iftar reminder | | --minutes <n> | Minutes before event (1-120) |

Examples:

# Enable notifications
ramadan notify --enable

# Set reminder to 10 minutes before
ramadan notify --minutes 10

# Enable with custom timing
ramadan notify --enable --minutes 30

Qibla

ramadan qibla [city]

Shows the Qibla direction (direction to Makkah) with an ASCII compass and bearing in degrees.

Examples:

# Qibla direction for saved/detected location
ramadan qibla

# Qibla direction for a specific city
ramadan qibla lhr

# Using full city name
ramadan qibla "New York"

Dua

ramadan dua [options]

| Flag | Description | |------|-------------| | -d, --day <number> | Show dua for a specific day (1-30) |

Displays the Ramadan dua of the day with Arabic text, transliteration, and English translation.

Examples:

# Today's dua
ramadan dua

# Dua for a specific day
ramadan dua --day 15

# Short flag
ramadan dua -d 27

Quran

ramadan quran [options]

| Flag | Description | |------|-------------| | -d, --day <number> | Show verse for a specific day (1-30) |

Displays a curated Quran verse with Arabic text, transliteration, English translation, and surah/ayah reference.

Examples:

# Today's verse
ramadan quran

# Verse for a specific day
ramadan quran --day 15

Hadith

ramadan hadith [options]

| Flag | Description | |------|-------------| | -d, --day <number> | Show hadith for a specific day (1-30) |

Displays a curated hadith with Arabic text, transliteration, English translation, source, and narrator.

Examples:

# Today's hadith
ramadan hadith

# Hadith for a specific day
ramadan hadith --day 27

Adhkar

ramadan adhkar <collection>

Displays adhkar (remembrance) collections. Collections: morning, evening, post-prayer.

Examples:

# Morning adhkar
ramadan adhkar morning

# Evening adhkar
ramadan adhkar evening

# Post-prayer adhkar
ramadan adhkar post-prayer

Track

ramadan track [prayer] [options]

| Flag | Description | |------|-------------| | --show | Show today's prayer tracking status | | --date <YYYY-MM-DD> | Track for a specific date | | --fasted | Mark the day as fasted | | --vacation | Mark the day as vacation (doesn't break streak) |

Track daily prayer completion. Prayers: fajr, dhuhr, asr, maghrib, isha, taraweeh.

Examples:

# Mark Fajr as complete
ramadan track fajr

# Mark Taraweeh as complete
ramadan track taraweeh

# Mark today as fasted
ramadan track --fasted

# Mark a vacation day (travel/illness)
ramadan track --vacation

# Show today's tracking status
ramadan track --show

# Track for a specific date
ramadan track fajr --date 2026-03-01

Goal

ramadan goal <action> [options]

| Action | Description | |--------|-------------| | add | Create a new goal | | update | Update goal progress | | list | List all goals | | delete | Delete a goal |

| Flag | Description | |------|-------------| | --title <title> | Goal title (for add) | | --target <n> | Target value (for add) | | --unit <unit> | Unit of measurement (for add) | | --id <id> | Goal ID (for update/delete) | | --progress <n> | Progress value (for update) |

Examples:

# Add a goal
ramadan goal add --title "Read Quran" --target 30 --unit juz

# Update progress
ramadan goal update --id "read-quran" --progress 15

# List all goals
ramadan goal list

# Delete a goal
ramadan goal delete --id "read-quran"

Stats

ramadan stats [options]

| Flag | Description | |------|-------------| | -w, --weekly | Show weekly summary |

Shows a consolidated summary of prayer completion rate, fasting streak, goal progress, and earned badges.

Examples:

# Full stats summary
ramadan stats

# Weekly summary
ramadan stats --weekly

Charity

ramadan charity <action> [options]

| Action | Description | |--------|-------------| | add | Log a new donation | | list | List all donations | | summary | Show donation summary |

| Flag | Description | |------|-------------| | --amount <n> | Donation amount (for add) | | --description <text> | Description (for add) | | --category <category> | Category, e.g. food, shelter, education (for add) |

Examples:

# Log a donation
ramadan charity add --amount 50 --description "Masjid fund"

# Log with category
ramadan charity add --amount 100 --description "Food bank" --category food

# List all donations
ramadan charity list

# View summary
ramadan charity summary

Zakat

ramadan zakat [options]

| Flag | Description | |------|-------------| | --cash <amount> | Cash and bank balances | | --gold <grams> | Gold in grams | | --silver <grams> | Silver in grams | | --investments <amount> | Investment value | | --property <amount> | Property value | | --debts <amount> | Outstanding debts |

Calculates Zakat (2.5%) based on wealth inputs with nisab thresholds for gold and silver.

Examples:

# Calculate Zakat
ramadan zakat --cash 10000 --gold 5000 --debts 2000

Compare

ramadan compare <city1> <city2> [city3] [city4]

Shows prayer times for 2-4 cities side by side.

Examples:

# Compare two cities
ramadan compare sf lhr

# Compare four cities
ramadan compare sf lhr dxb ist

Export

ramadan export [options]

| Flag | Description | |------|-------------| | -f, --format <format> | Export format: ical (default), csv, json | | -o, --output <path> | Output file path |

Examples:

# Export as iCal
ramadan export

# Export as CSV
ramadan export --format csv

# Export as JSON to a specific path
ramadan export --format json --output ~/ramadan-times.json

Widget

ramadan widget [city]

Launches a compact 3-line auto-refreshing terminal display showing location, Sehar, and Iftar times.

Examples:

# Widget for saved location
ramadan widget

# Widget for a specific city
ramadan widget lhr

Cache

ramadan cache [options]

| Flag | Description | |------|-------------| | --build | Prefetch prayer times for offline use | | --clear | Clear the cache | | --city <city> | City to cache (defaults to saved config) | | --days <n> | Number of days to cache (default: 30) |

Examples:

# Prefetch 30 days of prayer times
ramadan cache --build

# Prefetch for a specific city
ramadan cache --build --city lhr

# Prefetch 7 days
ramadan cache --build --days 7

# Clear cache
ramadan cache --clear

Profile

ramadan profile <action> [name] [options]

| Action | Description | |--------|-------------| | add | Create a new location profile | | use | Switch to a saved profile | | list | List all saved profiles | | delete | Delete a saved profile |

| Flag | Description | |------|-------------| | --city <city> | City for the profile | | --country <country> | Country for the profile |

Examples:

# Add a profile
ramadan profile add home --city Lahore --country Pakistan

# Add another profile
ramadan profile add work --city "San Francisco" --country US

# Switch profiles
ramadan profile use home

# List all profiles
ramadan profile list

# Delete a profile
ramadan profile delete work

Completion

ramadan completion <shell>

Generate shell completion scripts for tab-completion of commands, flags, and city aliases.

Examples:

# Bash
ramadan completion bash >> ~/.bashrc

# Zsh
ramadan completion zsh >> ~/.zshrc

# Fish
ramadan completion fish > ~/.config/fish/completions/ramadan.fish

Reset

# Clear all saved configuration
ramadan reset

Dashboard

# Launch interactive TUI dashboard
ramadan dashboard

# Or use the flag
ramadan --tui

Output Formats

Table (default)

ramadan

Displays a colored table with ASCII banner, prayer times (Roza, Sehar, Iftar, Date, Hijri), current status, and next event countdown.

JSON

ramadan --json

{
  "output": {
    "mode": "today",
    "location": "San Francisco, US",
    "hijriYear": "1446",
    "rows": [
      {
        "roza": 1,
        "sehar": "05:42 AM",
        "iftar": "06:15 PM",
        "date": "2025-03-01",
        "hijri": "1 Ramadan 1446"
      }
    ]
  }
}

Plain

ramadan --plain

Text-only output with no colors or ASCII art — suitable for piping and scripting.

Status-line

ramadan --status

Iftar in 2h 30m

Single-line output designed for embedding in tmux, polybar, i3status, or any status bar.

City Aliases

82 short codes covering major cities across 10 regions:

| Alias | City | |-------|------| | sf | San Francisco | | nyc | New York | | la | Los Angeles | | dc | Washington | | chi | Chicago | | tor | Toronto | | hou | Houston | | det | Detroit | | phi | Philadelphia | | bos | Boston | | mia | Miami | | atl | Atlanta | | van | Vancouver | | mtl | Montreal |

| Alias | City | |-------|------| | lhr | Lahore | | isb | Islamabad | | khi | Karachi | | mum | Mumbai | | del | Delhi | | dhk | Dhaka | | cmb | Colombo | | hyd | Hyderabad | | pew | Peshawar | | fsd | Faisalabad | | rwp | Rawalpindi | | ktm | Kathmandu |

| Alias | City | |-------|------| | dxb | Dubai | | jed | Jeddah | | ruh | Riyadh | | mak / makkah / mecca | Makkah | | mad / madinah / medina | Madinah | | doh | Doha | | kwt | Kuwait City | | mus | Muscat | | amm | Amman | | bgd | Baghdad | | bei | Beirut | | dam | Damascus | | ist | Istanbul |

| Alias | City | |-------|------| | cai | Cairo | | tun | Tunis | | alg | Algiers | | cas | Casablanca | | rab | Rabat | | tri | Tripoli |

| Alias | City | |-------|------| | lag | Lagos | | abj | Abuja | | nbo | Nairobi | | dar | Dar es Salaam | | mgq | Mogadishu | | acc | Accra | | kmp | Kampala | | dkr | Dakar |

| Alias | City | |-------|------| | lon | London | | par | Paris | | ber | Berlin | | ams | Amsterdam | | bru | Brussels | | osl | Oslo | | sto | Stockholm | | mdr | Madrid | | rom | Rome | | mun | Munich | | vie | Vienna | | cop | Copenhagen |

| Alias | City | |-------|------| | kul | Kuala Lumpur | | jkt | Jakarta | | sg | Singapore |

| Alias | City | |-------|------| | bkk | Bangkok | | hcm | Ho Chi Minh City | | tok | Tokyo | | pek | Beijing | | seo | Seoul |

| Alias | City | |-------|------| | tsh | Tashkent | | ala | Almaty | | bak | Baku |

| Alias | City | |-------|------| | syd | Sydney | | mel | Melbourne |

ramadan sf       # San Francisco
ramadan lhr      # Lahore
ramadan makkah   # Makkah, Saudi Arabia
ramadan ist      # Istanbul

Configuration

All settings are persisted to your OS config directory via conf.

| Setting | Flag | Example | |---------|------|---------| | City | --city | --city "San Francisco" | | Country | --country | --country US | | Latitude | --latitude | --latitude 37.7749 | | Longitude | --longitude | --longitude -122.4194 | | Timezone | --timezone | --timezone America/Los_Angeles | | Method | --method | --method 2 | | School | --school | --school 1 |

Defaults: Method 2 (ISNA), School 0 (Shafi).

Export/Import:

# Export your config
ramadan config --export > my-settings.json

# Import on another machine
ramadan config --import my-settings.json

Notifications

Native OS notifications powered by node-notifier.

| Setting | Default | |---------|---------| | Enabled | false | | Sehar Reminder | true | | Iftar Reminder | true | | Minutes Before | 15 |

Notifications display system alerts like "Sehar in 15 minutes" or "Iftar in 15 minutes" before each event.

TUI Dashboard

An interactive terminal dashboard built with React and Ink.

Header with location and Hijri date
Prayer Times Table with all 5 daily prayers
Live Countdown to the next Sehar or Iftar
Ramadan Progress showing day X of 30
Progress Bar showing fasting day progression
Status Badges for current fasting state
Interactive Settings Editor — edit all 9 settings (City, Country, Method, School, Theme, Locale, Notifications, Sehar/Iftar Reminders) via keyboard with inline dropdowns, text input, and instant toggles. Theme changes apply live.

ramadan dashboard
ramadan --tui

Internationalization

12 languages supported via i18next:

| Code | Language | |------|----------| | en | English | | ar | Arabic (العربية) | | ur | Urdu (اردو) | | tr | Turkish (Turkce) | | ms | Malay (Bahasa Melayu) | | bn | Bengali (বাংলা) | | fr | French (Francais) | | id | Indonesian (Bahasa Indonesia) | | es | Spanish (Espanol) | | de | German (Deutsch) | | hi | Hindi (हिन्दी) | | fa | Persian (فارسی) |

ramadan --locale ur
ramadan --locale ar
ramadan --locale es
ramadan --locale de
ramadan --locale hi

Calculation Methods

| ID | Method | |----|--------| | 0 | Jafari (Shia Ithna-Ashari) | | 1 | Karachi (Pakistan) | | 2 | ISNA (North America) | | 3 | MWL (Muslim World League) | | 4 | Makkah (Umm al-Qura) | | 5 | Egypt | | 7 | Tehran (Shia) | | 8 | Gulf Region | | 9 | Kuwait | | 10 | Qatar | | 11 | Singapore | | 12 | France | | 13 | Turkey | | 14 | Russia | | 15 | Moonsighting Committee | | 16 | Dubai | | 17 | Malaysia (JAKIM) | | 18 | Tunisia | | 19 | Algeria | | 20 | Indonesia | | 21 | Morocco | | 22 | Portugal | | 23 | Jordan |

Juristic Schools:

| ID | School | |----|--------| | 0 | Shafi (standard) | | 1 | Hanafi |

ramadan config --method 4 --school 1

Architecture

DI Container — Centralized dependency injection wiring 21 commands and all services
Command Pattern — Each CLI command implements validate() + execute() with centralized CommandError handling
Pure Registry — CommandFactory uses a Map-based registry with register()/get()/list() — no constructor params
Formatter Strategy — Pluggable output formatters (Table, JSON, Plain, Status-line, Qibla)
3 Geo-IP Providers — Fallback chain for automatic location detection
Geocoding — Open Meteo geocoding for city name resolution with timezone detection
File-based Caching — TTL-based cache with offline prefetch support
Zod Validation — Runtime schema validation with branded types (Latitude, Longitude, MethodId, SchoolId, RozaNumber)
React/Ink TUI — Terminal UI components with hooks and dynamic theme context
i18next Integration — Dynamic language switching with 12 locales, 80+ keys per locale, and interpolation
Custom Error Hierarchy — CommandError with error codes; single top-level handler replaces 32 scattered process.exit calls
Service-level Validation — Input validation in service layer (non-empty strings, positive numbers, date formats)
Country-Aware Defaults — Automatic calculation method and school recommendations per country

Tech Stack

Contributing

# Clone the repo
git clone https://github.com/HammadXCM/ramadan-cli-pro.git
cd ramadan-cli-pro

# Install dependencies
pnpm install

# Development mode (watch)
pnpm dev

# Run tests
pnpm test

# Lint & format
pnpm lint
pnpm format

# Type check
pnpm typecheck

# Full check (lint + typecheck + test + build)
pnpm check

PRs are welcome! Please open an issue first to discuss what you'd like to change.

Changelog

See CHANGELOG.md for a detailed list of changes in each release.

License

Author

Credits

This project is inspired by ramadan-cli by @ahmadawais.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

Features

Quick Start

Usage

Root Command

Config

Notify

Qibla

Dua

Quran

Hadith

Adhkar

Track

Goal

Stats

Charity

Zakat

Compare

Export

Widget

Cache

Profile

Completion

Reset

Dashboard

Output Formats

Table (default)

JSON

Plain

Status-line

City Aliases

Configuration

Notifications

TUI Dashboard

Internationalization

Calculation Methods

Architecture

Tech Stack

Contributing

Changelog

License

Author

Credits