Quick Start This guide will walk you through running Ramadan CLI for the first time and understanding the core features.
First Run
Run the CLI
Open your terminal and run: roza # or: npx ramadan-cli (if not installed globally)
On first run, you’ll see an interactive setup prompt.
Complete the Setup
The CLI will guide you through a one-time setup: ┌ 🌙 Ramadan CLI Setup │ ◇ Detecting your location... │ Detected: San Francisco, United States │ ◆ Enter your city │ San Francisco │ ◆ Enter your country │ United States │ ◇ Resolving city details... │ Detected timezone: America/Los_Angeles │ ◆ Select calculation method │ ● ISNA (North America) (Recommended) │ ○ Karachi (Pakistan) │ ○ MWL (Muslim World League) │ ... │ ◆ Select Asr school │ ● Shafi (Recommended) - Standard Asr timing │ ○ Hanafi - Later Asr timing │ ◆ Timezone preference │ ● Use detected timezone (America/Los_Angeles) │ ○ Set custom timezone │ ○ Do not set timezone override │ └ 🌙 Setup complete.
The CLI automatically detects your location, recommends the best calculation method for your country, and detects your timezone. Just press Enter to accept the defaults.
View Your Times
After setup, you’ll immediately see today’s Sehar and Iftar times: ██████ █████ ███ ███ █████ ██████ █████ ███ ██ ██ ██ ██ ██ ████ ████ ██ ██ ██ ██ ██ ██ ████ ██ ██████ ███████ ██ ████ ██ ███████ ██ ██ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████ ██ ██ ██ ████ 🌙 Ramadan CLI Sehar • Iftar • Ramadan timings Today Sehar/Iftar 📍 San Francisco, United States Roza Sehar Iftar Date Hijri ---------------------------------------------------------------- 15 5:30 AM 6:45 PM 05-03-2026 15 Ramadan 1447 Status: Roza in progress Up next: Iftar in 3h 25m Sehar uses Fajr. Iftar uses Maghrib.
Your settings are saved automatically. Next time you run roza, you’ll see times instantly without any setup.
Core Commands Now that you’re set up, here are the most common commands:
Today’s Times (Default) Shows today’s Sehar and Iftar times with a countdown to the next event.
Full Ramadan Month Displays all 30 days of Ramadan:
Ramadan 1447 (All Days) 📍 San Francisco, United States Roza Sehar Iftar Date Hijri ---------------------------------------------------------------- 1 5:45 AM 6:15 PM 19-02-2026 1 Ramadan 1447 2 5:44 AM 6:16 PM 20-02-2026 2 Ramadan 1447 3 5:43 AM 6:17 PM 21-02-2026 3 Ramadan 1447 ... 15 5:30 AM 6:45 PM 05-03-2026 15 Ramadan 1447 ← current 16 5:29 AM 6:46 PM 06-03-2026 16 Ramadan 1447 ← next ... 30 5:15 AM 7:00 PM 20-03-2026 30 Ramadan 1447 Status: Roza in progress Up next: Iftar in 3h 25m
Specific Roza Day roza --number 10 # or roza -n 10
Shows times for a specific roza (1-30):
Roza 10 Sehar/Iftar 📍 San Francisco, United States Roza Sehar Iftar Date Hijri ---------------------------------------------------------------- 10 5:35 AM 6:30 PM 28-02-2026 10 Ramadan 1447
Check Different City roza "San Francisco" roza lahore roza "New York"
Check times for any city without changing your saved location:
City with spaces
Single word city
City with country
City alias
Combine Commands You can combine flags for powerful queries:
# Full month for a different city roza "Tokyo" --all # Specific roza in another city roza "Lahore" --number 27 # Different city with plain output (no banner) roza "Makkah" --plain
Output Modes Ramadan CLI offers multiple output formats for different use cases:
Standard (Default)
Plain Text
JSON
Status Bar
Beautiful terminal output with ASCII banner, colors, and countdown: Perfect for interactive terminal use. Clean output without the ASCII banner: roza --plain # or roza -p
Good for simpler terminals or when you want less visual noise. Structured JSON output for scripts and automation: Example output: { "mode" : "today" , "location" : "San Francisco, United States" , "hijriYear" : 1447 , "rows" : [ { "roza" : 15 , "sehar" : "5:30 AM" , "iftar" : "6:45 PM" , "date" : "05-03-2026" , "hijri" : "15 Ramadan 1447" } ] }
Single-line output perfect for status bars (tmux, i3bar, etc.): roza --status # or roza -s
Output: Use in your status bar config: # tmux.conf set -g status-right '#(roza --status)'
Understanding the Output Let’s break down what each part means:
Sehar = Fajr prayer time (pre-dawn meal)Iftar = Maghrib prayer time (breaking fast)Times are shown in 12-hour format (AM/PM)
The CLI shows your current state:
Before roza day : Before the first Ramadan daySehar window open : Time to eat Sehar before fasting startsRoza in progress : Currently fastingIftar time : Time to break fastNext day Sehar : After Iftar, counting down to tomorrow’s Sehar Countdown format: 3h 25m (hours and minutes) or 45m (minutes only)
When using --all, the CLI highlights:
← current: Today’s roza← next: Tomorrow’s roza This helps you quickly find relevant days in the full month view. Common Use Cases
Morning Check Quick check of today’s times when you wake up
Plan Ahead See the entire month to plan your schedule
Travel Check times for your destination before or during travel
Status Bar Integrate with your terminal status bar or shell prompt Pro Tips Alias in your shell : Add to your ~/.bashrc or ~/.zshrc for even faster access:alias r = "roza" alias ra = "roza --all"
Check multiple cities quickly : Chain commands to compare:roza "San Francisco" && echo "---" && roza "Lahore"
Use in scripts : The --json flag makes it easy to parse in scripts:#!/bin/bash iftar_time = $( roza --json | jq -r '.rows[0].iftar' ) echo "Don't forget! Iftar is at $iftar_time "
Reset Configuration If you want to start over or your location changed:
This clears all saved settings. The next time you run roza, you’ll go through the setup again.
What’s Next? Ramadan CLI uses the Aladhan Prayer Times API to fetch accurate prayer times based on your location and selected calculation method. 