JSON Output

Use JSON mode for programmatic access to Ramadan timings

Overview

The --json flag enables JSON-only output to stdout, making ramadan-cli perfect for scripts, automation, and programmatic access. This mode skips all interactive prompts and outputs structured data.

Basic Usage

ramadan-cli --json
ramadan-cli sf --json
ramadan-cli "Lahore, Pakistan" --json

JSON mode automatically skips interactive setup and falls back to IP geolocation if no config exists.

Output Structure

The JSON output follows this structure:

{
  "mode": "today",
  "location": "San Francisco, United States",
  "hijriYear": 1447,
  "rows": [
    {
      "roza": 1,
      "sehar": "5:30 AM",
      "iftar": "7:45 PM",
      "date": "28-02-2026",
      "hijri": "1 Ramadan 1447"
    }
  ]
}

Field Definitions

mode · string · required

The display mode used:

• "today" - Single day view (default)
• "all" - Complete Ramadan month (30 days)
• "number" - Specific roza number

location · string · required

The location address used for the query (city, country, or coordinates)

hijriYear · number · required

The Hijri year for the Ramadan timings

rows · array · required

Array of Ramadan day objects, each containing:

Show Row Object Properties

roza · number

The roza (fast) day number (1-30)

sehar · string

Sehar (Fajr) time in 12-hour format with AM/PM

iftar · string

Iftar (Maghrib) time in 12-hour format with AM/PM

date · string

Gregorian date in DD-MM-YYYY format

hijri · string

Hijri date in “day month year” format (e.g., “1 Ramadan 1447”)

Output Modes

Today Mode (Default)

Shows timings for the current Ramadan day or next upcoming Ramadan:

Command

ramadan-cli --json

All Mode

Shows complete Ramadan month (30 days):

Command

ramadan-cli --all --json

Specific Roza Mode

Shows timings for a specific roza day:

Command

ramadan-cli --number 15 --json

Error Handling

Error Format

When an error occurs with --json, the error payload is written to stderr (not stdout):

{
  "ok": false,
  "error": {
    "code": "LOCATION_DETECTION_FAILED",
    "message": "Could not detect location. Pass a city like `ramadan-cli \"Lahore\"`."  
  }
}

Error Codes

Common Errors

Code	Description	Example
LOCATION_DETECTION_FAILED	Could not detect location	No city specified and IP geo failed
INVALID_FLAG_COMBINATION	Conflicting flags used	--all with --number
INVALID_FIRST_ROZA_DATE	Invalid date format	Wrong format for --first-roza-date

API Errors

Code	Description
PRAYER_TIMES_FETCH_FAILED	Could not fetch prayer times from API
RAMADAN_CALENDAR_FETCH_FAILED	Could not fetch Ramadan calendar
ROZA_NOT_FOUND	Specified roza number not found

Other Errors

Code	Description
RAMADAN_CLI_ERROR	General CLI error
UNKNOWN_ERROR	Unexpected error occurred

Handling Errors in Scripts

Shell Script

#!/bin/bash

# Capture stdout and stderr separately
OUTPUT=$(ramadan-cli --json 2>error.json)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
    echo "Success:"
    echo "$OUTPUT" | jq '.'
else
    echo "Error:"
    jq '.error' error.json
    exit 1
fi

Parsing Examples

Extract Specific Fields

Today's Iftar Time

ramadan-cli --json | jq -r '.rows[0].iftar'
# Output: 7:45 PM

Complex Queries

Find Earliest Sehar

ramadan-cli --all --json | jq -r '[.rows[].sehar] | min'

Integration Examples

Shell Script Integration

#!/bin/bash
set -euo pipefail

# Fetch Ramadan data
DATA=$(ramadan-cli --json 2>/dev/null || echo '{"rows":[]}')

# Check if we have data
IF_COUNT=$(echo "$DATA" | jq '.rows | length')

if [ "$IF_COUNT" -eq 0 ]; then
    echo "No Ramadan data available"
    exit 1
fi

# Extract first row
ROZA=$(echo "$DATA" | jq -r '.rows[0].roza')
SEHAR=$(echo "$DATA" | jq -r '.rows[0].sehar')
IFTAR=$(echo "$DATA" | jq -r '.rows[0].iftar')

echo "Roza $ROZA"
echo "Sehar: $SEHAR"
echo "Iftar: $IFTAR"

API Wrapper

// ramadan-api.js
const { execSync } = require('child_process');

class RamadanAPI {
  static async getToday(city = null) {
    const cmd = city ? `ramadan-cli "${city}" --json` : 'ramadan-cli --json';
    try {
      const output = execSync(cmd, { encoding: 'utf8' });
      return JSON.parse(output);
    } catch (error) {
      const errorData = JSON.parse(error.stderr.toString());
      throw new Error(errorData.error.message);
    }
  }

  static async getAll(city = null) {
    const cmd = city ? `ramadan-cli "${city}" --all --json` : 'ramadan-cli --all --json';
    try {
      const output = execSync(cmd, { encoding: 'utf8' });
      return JSON.parse(output);
    } catch (error) {
      const errorData = JSON.parse(error.stderr.toString());
      throw new Error(errorData.error.message);
    }
  }

  static async getRoza(number, city = null) {
    const cmd = city 
      ? `ramadan-cli "${city}" --number ${number} --json`
      : `ramadan-cli --number ${number} --json`;
    try {
      const output = execSync(cmd, { encoding: 'utf8' });
      return JSON.parse(output);
    } catch (error) {
      const errorData = JSON.parse(error.stderr.toString());
      throw new Error(errorData.error.message);
    }
  }
}

module.exports = RamadanAPI;

Command Combinations

With Location Override

# One-off city query
ramadan-cli "Istanbul, Turkey" --json
ramadan-cli cairo --json
ramadan-cli sf --all --json

With Custom First Roza Date

# Set custom start date
ramadan-cli --first-roza-date 2026-02-19 --json
ramadan-cli --first-roza-date 2026-02-19 --all --json

Combined with Config

# Configure once
ramadan-cli config --city "London" --country "United Kingdom"

# Use JSON output with saved config
ramadan-cli --json
ramadan-cli --all --json

Best Practices

Always Parse stderr for Errors

Success output goes to stdout, errors to stderr:

OUTPUT=$(ramadan-cli --json 2>error.json)
if [ $? -ne 0 ]; then
    jq '.error' error.json
fi

Use jq for Parsing

jq is the recommended tool for parsing JSON output:

ramadan-cli --json | jq -r '.rows[0].iftar'

Handle Missing Data Gracefully

Check array lengths before accessing:

COUNT=$(ramadan-cli --json | jq '.rows | length')
if [ "$COUNT" -gt 0 ]; then
    # Safe to access .rows[0]
fi

Cache API Responses

Prayer times don’t change frequently. Cache the JSON output:

CACHE_FILE="/tmp/ramadan-cache.json"
if [ ! -f "$CACHE_FILE" ] || [ $(find "$CACHE_FILE" -mmin +60) ]; then
    ramadan-cli --all --json > "$CACHE_FILE"
fi
cat "$CACHE_FILE"

See Also

Agent Usage

Learn about using ramadan-cli as an agent skill

Status Line Mode

Single-line output for status bars