JSON Output

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

string

required

The display mode used:

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

string

required

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

number

required

The Hijri year for the Ramadan timings

array

required

Array of Ramadan day objects, each containing:

Show Row Object Properties

number

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

string

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

string

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

string

Gregorian date in DD-MM-YYYY format

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:

ramadan-cli --json

{
  "mode": "today",
  "location": "New York, United States",
  "hijriYear": 1447,
  "rows": [
    {
      "roza": 1,
      "sehar": "5:15 AM",
      "iftar": "6:30 PM",
      "date": "28-02-2026",
      "hijri": "1 Ramadan 1447"
    }
  ]
}

All Mode

Shows complete Ramadan month (30 days):

ramadan-cli --all --json

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

Specific Roza Mode

Shows timings for a specific roza day:

ramadan-cli --number 15 --json

{
  "mode": "number",
  "location": "Lahore, Pakistan",
  "hijriYear": 1447,
  "rows": [
    {
      "roza": 15,
      "sehar": "4:30 AM",
      "iftar": "6:45 PM",
      "date": "14-03-2026",
      "hijri": "15 Ramadan 1447"
    }
  ]
}

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
API Errors
Other 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`

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

Code	Description
`RAMADAN_CLI_ERROR`	General CLI error
`UNKNOWN_ERROR`	Unexpected error occurred

Handling Errors in Scripts

#!/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

const { execSync } = require('child_process');

try {
  const output = execSync('ramadan-cli --json', {
    encoding: 'utf8',
    stdio: ['pipe', 'pipe', 'pipe']
  });
  const data = JSON.parse(output);
  console.log('Sehar:', data.rows[0].sehar);
  console.log('Iftar:', data.rows[0].iftar);
} catch (error) {
  const stderr = error.stderr.toString();
  const errorData = JSON.parse(stderr);
  console.error('Error:', errorData.error.message);
  process.exit(1);
}

import json
import subprocess
import sys

try:
    result = subprocess.run(
        ['ramadan-cli', '--json'],
        capture_output=True,
        text=True,
        check=True
    )
    data = json.loads(result.stdout)
    print(f"Sehar: {data['rows'][0]['sehar']}")
    print(f"Iftar: {data['rows'][0]['iftar']}")
except subprocess.CalledProcessError as e:
    error_data = json.loads(e.stderr)
    print(f"Error: {error_data['error']['message']}", file=sys.stderr)
    sys.exit(1)

Parsing Examples

Extract Specific Fields

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

ramadan-cli --json | jq -r '.location'
# Output: San Francisco, United States

ramadan-cli --all --json | jq -r '.rows[].sehar'
# Output: Multiple lines of sehar times

ramadan-cli --number 10 --json | jq -r '.rows[0].date'
# Output: 09-03-2026

Complex Queries

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

ramadan-cli --all --json | jq '.rows | length'

ramadan-cli --all --json | jq '.rows[] | select(.roza == 15)'

ramadan-cli --all --json | jq -r '.rows[] | [.roza, .sehar, .iftar, .date] | @csv'

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"

Agent Usage

Learn about using ramadan-cli as an agent skill

Status Line Mode

Single-line output for status bars

Get Started

Usage

Features

Integration

Overview

Basic Usage

Output Structure

Field Definitions

Output Modes

Today Mode (Default)

All Mode

Specific Roza Mode

Error Handling

Error Format

Error Codes

Handling Errors in Scripts

Parsing Examples

Extract Specific Fields

Complex Queries

Integration Examples

Shell Script Integration

API Wrapper

Command Combinations

With Location Override

With Custom First Roza Date

Combined with Config

Best Practices

See Also

Agent Usage

Status Line Mode

​Overview

​Basic Usage

​Output Structure

​Field Definitions

​Output Modes

​Today Mode (Default)

​All Mode

​Specific Roza Mode

​Error Handling

​Error Format

​Error Codes

​Handling Errors in Scripts

​Parsing Examples

​Extract Specific Fields

​Complex Queries

​Integration Examples

​Shell Script Integration

​API Wrapper

​Command Combinations

​With Location Override

​With Custom First Roza Date

​Combined with Config

​Best Practices

​See Also

Agent Usage

Status Line Mode

Overview

Basic Usage

Output Structure

Field Definitions

Output Modes

Today Mode (Default)

All Mode

Specific Roza Mode

Error Handling

Error Format

Error Codes

Handling Errors in Scripts

Parsing Examples

Extract Specific Fields

Complex Queries

Integration Examples

Shell Script Integration

API Wrapper

Command Combinations

With Location Override

With Custom First Roza Date

Combined with Config

Best Practices

See Also