Output Modes

Ramadan CLI offers multiple output modes designed for different use cases, from human-readable terminal output to machine-parsable JSON for scripts and agents.

Default Mode: Rich Terminal Output

Without any output flags, you get a beautifully formatted terminal display:

roza

  ██████   █████  ███    ███  █████  ██████   █████  ███    ██ 
  ██   ██ ██   ██ ████  ████ ██   ██ ██   ██ ██   ██ ████   ██ 
  ██████  ███████ ██ ████ ██ ███████ ██   ██ ███████ ██ ██  ██ 
  ██   ██ ██   ██ ██  ██  ██ ██   ██ ██   ██ ██   ██ ██  ██ ██ 
  ██   ██ ██   ██ ██      ██ ██   ██ ██████  ██   ██ ██   ████ 

  Today Sehar/Iftar
  📍 San Francisco, United States

  Roza  Sehar     Iftar     Date            Hijri
  --------------------------------------------------------------
  15    5:42 AM   7:23 PM   15-03-2026      15 Ramadan 1447 ← current

  Status: Roza in progress
  Up next: Iftar in 3h 45m

  Sehar uses Fajr. Iftar uses Maghrib.

This mode includes:

ASCII art banner
Color-coded output (green for Ramadan branding)
Current status with countdown timer
Row annotations (← current, ← next)
Footer note explaining time semantics

Plain Text Mode

Use --plain or -p to remove the ASCII banner while keeping the formatted table:

roza --plain
roza -p

RAMADAN CLI
  Today Sehar/Iftar
  📍 Lahore, Pakistan

  Roza  Sehar     Iftar     Date            Hijri
  --------------------------------------------------------------
  12    4:58 AM   6:17 PM   11-03-2026      12 Ramadan 1447 ← current

  Status: Roza in progress
  Up next: Iftar in 2h 15m

  Sehar uses Fajr. Iftar uses Maghrib.

Plain mode is useful when:

Running in environments where ASCII art doesn’t render well
You want cleaner, more compact output
Integrating with tools that parse terminal output

JSON Mode

Use --json or -j to get structured JSON output for scripts and automation:

roza --json
roza -j

Success Response

{
  "mode": "today",
  "location": "San Francisco, United States",
  "hijriYear": 1447,
  "rows": [
    {
      "roza": 15,
      "sehar": "5:42 AM",
      "iftar": "7:23 PM",
      "date": "15-03-2026",
      "hijri": "15 Ramadan 1447"
    }
  ]
}

JSON Mode Values

The mode field indicates what data is being returned:

Mode	Description	When Used
`today`	Single day (current or first)	Default run without flags
`all`	Full 30-day calendar	When using `--all` flag
`number`	Specific roza day	When using `--number <1-30>` flag

Full Calendar JSON

roza "Dubai, UAE" --all --json

{
  "mode": "all",
  "location": "Dubai, United Arab Emirates",
  "hijriYear": 1447,
  "rows": [
    {
      "roza": 1,
      "sehar": "5:03 AM",
      "iftar": "6:22 PM",
      "date": "28-02-2026",
      "hijri": "1 Ramadan 1447"
    },
    {
      "roza": 2,
      "sehar": "5:02 AM",
      "iftar": "6:23 PM",
      "date": "01-03-2026",
      "hijri": "2 Ramadan 1447"
    }
    // ... 28 more days
  ]
}

Error Response

When an error occurs in JSON mode, the error is written to stderr:

roza --json --first-roza-date invalid-date 2>&1

{
  "ok": false,
  "error": {
    "code": "INVALID_FIRST_ROZA_DATE",
    "message": "Invalid first roza date. Use YYYY-MM-DD."
  }
}

Error Codes

JSON errors include standardized error codes:

Code	Description
`INVALID_FIRST_ROZA_DATE`	First roza date is not in YYYY-MM-DD format
`INVALID_FLAG_COMBINATION`	Conflicting flags (e.g., `--all` with `--number`)
`PRAYER_TIMES_FETCH_FAILED`	Failed to fetch prayer times from API
`RAMADAN_CALENDAR_FETCH_FAILED`	Failed to fetch Ramadan calendar
`LOCATION_DETECTION_FAILED`	Could not detect location
`ROZA_NOT_FOUND`	Specified roza number not found
`RAMADAN_CLI_ERROR`	General CLI error
`UNKNOWN_ERROR`	Unexpected error

Exit codes: 0 for success, 1 for any error condition

Status Line Mode

Use --status or -s for a single-line output showing the next event. Perfect for status bars, shell prompts, and coding agents:

roza --status
roza -s

Example Outputs

Before Sehar:

Sehar in 5h 23m

During Sehar window:

Fast starts in 45m

During fasting:

Iftar in 6h 12m

After Iftar:

Sehar in 9h 8m

Before Ramadan:

Sehar in 15d 8h 25m

Status Line Logic

The status line is generated by the getHighlightState() function:

const getHighlightState = (day: PrayerData): HighlightState | null => {
  // Calculates current state and countdown based on:
  // - Current time in the location's timezone
  // - Sehar time (Fajr)
  // - Iftar time (Maghrib)
  // - Current date vs roza date
};

The countdown format:

Hours and minutes: 6h 12m
Minutes only (under 1 hour): 45m
Days, hours, minutes: 15d 8h 25m

Status Line with City

roza -s --city "London"
roza -s "Karachi, Pakistan"

Use Cases for Status Line

Shell Prompt
Tmux Status Bar
Waybar/Polybar
AI Agents

Add Ramadan countdown to your shell prompt:

# In your .bashrc or .zshrc
export PS1="$(roza -s) $ "

Show next event in tmux:

# In .tmux.conf
set -g status-right "#(roza -s)"

Display in your desktop status bar:

{
  "custom/ramadan": {
    "exec": "roza -s",
    "interval": 60
  }
}

Agents can check status without verbose output:

# Agent checks Ramadan status
STATUS=$(roza -s)
echo "Current: $STATUS"

Silent Failures

Status mode fails silently (no output) if:

Location cannot be detected
API request fails
No configuration exists and interactive setup is skipped

This prevents status bars from showing error messages. Use roza without flags to diagnose issues.

JSON Mode Behavior

Non-Interactive

When using --json, the CLI skips interactive setup:

const query = await resolveQuery({
  city: opts.city,
  allowInteractiveSetup: !opts.json, // No prompts in JSON mode
});

If no configuration exists, it attempts automatic location detection.

I/O Streams

# Success output goes to stdout
roza --json > ramadan.json

# Error output goes to stderr
roza --json --first-roza-date bad 2> error.json

# Capture both
roza --json > data.json 2> error.json

Combining Output Modes with Other Flags

Plain + All

roza --plain --all

Clean table output with all 30 days.

JSON + Number

roza --json --number 27

{
  "mode": "number",
  "location": "Istanbul, Turkey",
  "hijriYear": 1447,
  "rows": [
    {
      "roza": 27,
      "sehar": "4:15 AM",
      "iftar": "6:55 PM",
      "date": "26-03-2026",
      "hijri": "27 Ramadan 1447"
    }
  ]
}

JSON + City + Custom Date

roza --json "Mecca, Saudi Arabia" --first-roza-date 2026-03-01 --all

Get structured data for a specific city with custom Ramadan dates.

Output Mode Precedence

You cannot combine certain output modes:

roza --json --status
# ⚠️ --json takes precedence

roza --plain --status
# ⚠️ --status takes precedence (single line, no table)

Only use one output mode flag at a time: --json, --status, or --plain. If multiple are provided, the behavior is:

--status (highest priority)
--json
--plain

Color Output

Default and plain modes use terminal colors:

Green (ramadanGreen): Headers, status labels
Yellow: Countdown times, “next” annotations
White: Data values
Dim/Gray: Table borders, footer notes

Colors are defined in src/ui/theme.ts:

export const ramadanGreen = (text: string): string => pc.hex('#81F096')(text);

JSON and status modes never include color codes.

Practical Examples

Script Integration

#!/bin/bash
# Check if it's time for Iftar

DATA=$(roza --json)
MODE=$(echo $DATA | jq -r '.mode')

if [ "$MODE" = "today" ]; then
  IFTAR=$(echo $DATA | jq -r '.rows[0].iftar')
  echo "Today's Iftar: $IFTAR"
fi

Desktop Notification

# Send notification with next event
STATUS=$(roza -s)
notify-send "Ramadan" "$STATUS"

CSV Export

# Convert JSON to CSV
roza --all --json | jq -r '.rows[] | [.roza, .sehar, .iftar, .date, .hijri] | @csv' > ramadan.csv

Ramadan Calendar - View full month or specific days
Location Detection - How location affects output
Custom First Roza - Using custom dates with different outputs

Get Started

Usage

Features

Integration

Default Mode: Rich Terminal Output

Plain Text Mode

JSON Mode

Success Response

JSON Mode Values

Full Calendar JSON

Error Response

Error Codes

Status Line Mode

Example Outputs

Status Line Logic

Status Line with City

Use Cases for Status Line

Silent Failures

JSON Mode Behavior

Non-Interactive

I/O Streams

Combining Output Modes with Other Flags

Plain + All

JSON + Number

JSON + City + Custom Date

Output Mode Precedence

Color Output

Practical Examples

Script Integration

Desktop Notification

CSV Export

Get Started

Usage

Features

Integration

Documentation Index

​Default Mode: Rich Terminal Output

​Plain Text Mode

​JSON Mode

​Success Response

​JSON Mode Values

​Full Calendar JSON

​Error Response

​Error Codes

​Status Line Mode

​Example Outputs

​Status Line Logic

​Status Line with City

​Use Cases for Status Line

​Silent Failures

​JSON Mode Behavior

​Non-Interactive

​I/O Streams

​Combining Output Modes with Other Flags

​Plain + All

​JSON + Number

​JSON + City + Custom Date

​Output Mode Precedence

​Color Output

​Practical Examples

​Script Integration

​Desktop Notification

​CSV Export

​Related Features

Default Mode: Rich Terminal Output

Plain Text Mode

JSON Mode

Success Response

JSON Mode Values

Full Calendar JSON

Error Response

Error Codes

Status Line Mode

Example Outputs

Status Line Logic

Status Line with City

Use Cases for Status Line

Silent Failures

JSON Mode Behavior

Non-Interactive

I/O Streams

Combining Output Modes with Other Flags

Plain + All

JSON + Number

JSON + City + Custom Date

Output Mode Precedence

Color Output

Practical Examples

Script Integration

Desktop Notification

CSV Export

Related Features