> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ahmadawais/ramadan-cli/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Run the CLI">
    Open your terminal and run:

    ```bash theme={null}
    roza
    # or: npx ramadan-cli (if not installed globally)
    ```

    On first run, you'll see an interactive setup prompt.
  </Step>

  <Step title="Complete the Setup">
    The CLI will guide you through a one-time setup:

    ```plaintext theme={null}
    ┌  🌙 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.
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="View Your Times">
    After setup, you'll immediately see today's Sehar and Iftar times:

    ```plaintext theme={null}
    ██████  █████  ███    ███  █████  ██████   █████  ███    ██
    ██   ██ ██   ██ ████  ████ ██   ██ ██   ██ ██   ██ ████   ██
    ██████  ███████ ██ ████ ██ ███████ ██   ██ ███████ ██ ██  ██
    ██   ██ ██   ██ ██  ██  ██ ██   ██ ██   ██ ██   ██ ██  ██ ██
    ██   ██ ██   ██ ██      ██ ██   ██ ██████  ██   ██ ██   ████

    🌙 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.
    ```
  </Step>
</Steps>

<Tip>
  Your settings are saved automatically. Next time you run `roza`, you'll see times instantly without any setup.
</Tip>

## Core Commands

Now that you're set up, here are the most common commands:

### Today's Times (Default)

```bash theme={null}
roza
```

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

### Full Ramadan Month

```bash theme={null}
roza --all
# or
roza -a
```

Displays all 30 days of Ramadan:

```plaintext theme={null}
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

```bash theme={null}
roza --number 10
# or
roza -n 10
```

Shows times for a specific roza (1-30):

```plaintext theme={null}
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

```bash theme={null}
roza "San Francisco"
roza lahore
roza "New York"
```

Check times for any city without changing your saved location:

<CodeGroup>
  ```bash City with spaces theme={null}
  roza "San Francisco"
  ```

  ```bash Single word city theme={null}
  roza lahore
  roza vancouver
  roza makkah
  ```

  ```bash City with country theme={null}
  roza "Karachi, Pakistan"
  roza "London, United Kingdom"
  ```

  ```bash City alias theme={null}
  roza sf  # Expands to San Francisco
  ```
</CodeGroup>

### Combine Commands

You can combine flags for powerful queries:

```bash theme={null}
# 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:

<Tabs>
  <Tab title="Standard (Default)">
    Beautiful terminal output with ASCII banner, colors, and countdown:

    ```bash theme={null}
    roza
    ```

    Perfect for interactive terminal use.
  </Tab>

  <Tab title="Plain Text">
    Clean output without the ASCII banner:

    ```bash theme={null}
    roza --plain
    # or
    roza -p
    ```

    Good for simpler terminals or when you want less visual noise.
  </Tab>

  <Tab title="JSON">
    Structured JSON output for scripts and automation:

    ```bash theme={null}
    roza --json
    # or
    roza -j
    ```

    Example output:

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Status Bar">
    Single-line output perfect for status bars (tmux, i3bar, etc.):

    ```bash theme={null}
    roza --status
    # or
    roza -s
    ```

    Output:

    ```plaintext theme={null}
    Iftar in 3h 25m
    ```

    Use in your status bar config:

    ```bash theme={null}
    # tmux.conf
    set -g status-right '#(roza --status)'
    ```
  </Tab>
</Tabs>

## Understanding the Output

Let's break down what each part means:

<Frame>
  <img src="https://raw.githubusercontent.com/ahmadawais/ramadan-cli/refs/heads/main/.github/ramadan.gif" alt="Ramadan CLI Output" />
</Frame>

<AccordionGroup>
  <Accordion title="Sehar and Iftar" icon="utensils">
    * **Sehar** = Fajr prayer time (pre-dawn meal)
    * **Iftar** = Maghrib prayer time (breaking fast)
    * Times are shown in 12-hour format (AM/PM)
  </Accordion>

  <Accordion title="Status and Countdown" icon="clock">
    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)
  </Accordion>

  <Accordion title="Date Formats" icon="calendar">
    Two date formats are shown:

    * **Gregorian**: Standard calendar (e.g., `05-03-2026` = March 5, 2026)
    * **Hijri**: Islamic calendar (e.g., `15 Ramadan 1447`)
  </Accordion>

  <Accordion title="Current and Next Markers" icon="arrow-right">
    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.
  </Accordion>
</AccordionGroup>

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Morning Check" icon="sunrise">
    ```bash theme={null}
    roza
    ```

    Quick check of today's times when you wake up
  </Card>

  <Card title="Plan Ahead" icon="calendar-days">
    ```bash theme={null}
    roza -a
    ```

    See the entire month to plan your schedule
  </Card>

  <Card title="Travel" icon="plane">
    ```bash theme={null}
    roza "Dubai"
    ```

    Check times for your destination before or during travel
  </Card>

  <Card title="Status Bar" icon="window-maximize">
    ```bash theme={null}
    roza -s
    ```

    Integrate with your terminal status bar or shell prompt
  </Card>
</CardGroup>

## Pro Tips

<Tip>
  **Alias in your shell**: Add to your `~/.bashrc` or `~/.zshrc` for even faster access:

  ```bash theme={null}
  alias r="roza"
  alias ra="roza --all"
  ```
</Tip>

<Tip>
  **Check multiple cities quickly**: Chain commands to compare:

  ```bash theme={null}
  roza "San Francisco" && echo "---" && roza "Lahore"
  ```
</Tip>

<Tip>
  **Use in scripts**: The `--json` flag makes it easy to parse in scripts:

  ```bash theme={null}
  #!/bin/bash
  iftar_time=$(roza --json | jq -r '.rows[0].iftar')
  echo "Don't forget! Iftar is at $iftar_time"
  ```
</Tip>

## Reset Configuration

If you want to start over or your location changed:

```bash theme={null}
ramadan-cli reset
```

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

## What's Next?

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/usage/commands">
    Explore all available commands and flags
  </Card>

  <Card title="Configuration" icon="gear" href="/usage/configuration">
    Learn about advanced configuration options
  </Card>

  <Card title="Custom Dates" icon="calendar-plus" href="/features/custom-first-roza">
    Override Ramadan start dates for moon sighting
  </Card>

  <Card title="Integration" icon="plug" href="/integration/agent-usage">
    Integrate with status bars, scripts, and agents
  </Card>
</CardGroup>

***

<Note>
  Ramadan CLI uses the [Aladhan Prayer Times API](https://aladhan.com/prayer-times-api) to fetch accurate prayer times based on your location and selected calculation method.
</Note>