Quick Start

Get started with Ramadan CLI in under a minute

Quick Start

This guide will walk you through running Ramadan CLI for the first time and understanding the core features.

First Run

1. 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.

2. 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.

3. 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)

roza

Shows today’s Sehar and Iftar times with a countdown to the next event.

Full Ramadan Month

roza --all
# or
roza -a

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

roza "San Francisco"

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)

Beautiful terminal output with ASCII banner, colors, and countdown:

roza

Perfect for interactive terminal use.

Plain Text

Clean output without the ASCII banner:

roza --plain
# or
roza -p

Good for simpler terminals or when you want less visual noise.

JSON

Structured JSON output for scripts and automation:

roza --json
# or
roza -j

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"
    }
  ]
}

Status Bar

Single-line output perfect for status bars (tmux, i3bar, etc.):

roza --status
# or
roza -s

Output:

Iftar in 3h 25m

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 and Iftar

• Sehar = Fajr prayer time (pre-dawn meal)
• Iftar = Maghrib prayer time (breaking fast)
• Times are shown in 12-hour format (AM/PM)

Status and Countdown

The CLI shows your current state:

• Before roza day: Before the first Ramadan day
• Sehar window open: Time to eat Sehar before fasting starts
• Roza in progress: Currently fasting
• Iftar time: Time to break fast
• Next day Sehar: After Iftar, counting down to tomorrow’s Sehar

Countdown format: 3h 25m (hours and minutes) or 45m (minutes only)

Date Formats

Two date formats are shown:

• Gregorian: Standard calendar (e.g., 05-03-2026 = March 5, 2026)
• Hijri: Islamic calendar (e.g., 15 Ramadan 1447)

Current and Next Markers

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

roza

Quick check of today’s times when you wake up

Plan Ahead

roza -a

See the entire month to plan your schedule

Travel

roza "Dubai"

Check times for your destination before or during travel

Status Bar

roza -s

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:

ramadan-cli reset

This clears all saved settings. The next time you run roza, you’ll go through the setup again.

What’s Next?

CLI Reference

Explore all available commands and flags

Configuration

Learn about advanced configuration options

Custom Dates

Override Ramadan start dates for moon sighting

Integration

Integrate with status bars, scripts, and agents

---

Ramadan CLI uses the Aladhan Prayer Times API to fetch accurate prayer times based on your location and selected calculation method.