Skip to main content

​
Overview

Ramadan CLI saves your configuration to avoid re-entering location and prayer settings every time. Configuration includes:
  • Location: City, country, latitude, longitude
  • Prayer Settings: Calculation method, juristic school, timezone
  • Custom Overrides: First roza date (optional)

​
First-Run Setup

When you run the CLI for the first time in a terminal (TTY), you’ll see an interactive setup: 
roza

​
Interactive Setup Flow

The setup uses Clack prompts to guide you through configuration:
  1. Location Detection
    • Automatically detects your location via IP geolocation
    • Shows detected city and country
    • Asks for confirmation
    • Allows manual entry if auto-detection fails
  2. Calculation Method
    • Recommends a method based on your country
    • Shows available methods (0-23)
    • You can accept recommendation or choose manually
  3. Juristic School
    • Recommends school based on your country
    • Options: Shafi (0) or Hanafi (1)
    • Affects Asr prayer time calculation
  4. Timezone
    • Auto-detects timezone from location
    • Can be manually set if needed
    • Ensures accurate countdown times

​
Auto-Detection

The CLI uses multiple IP geolocation providers with fallbacks: 
# First run attempts auto-detection
roza
If auto-detection succeeds: 
✔ Detected location: San Francisco, United States
  Use this location? (y/n)
If auto-detection fails: 
✖ Could not auto-detect location
  Please enter your city manually

​
When Interactive Setup Runs

Interactive setup runs when:
  • First time using the CLI
  • After roza reset
  • After roza config --clear
  • Running in a TTY (terminal)
  • No saved configuration exists
Passing a city as an argument temporarily bypasses your saved config for that run only.

​
Non-Interactive Configuration

Use the config command to manage settings without prompts.

​
Setting Configuration

roza config [options]
Example: Complete Setup 
roza config \
  --city "San Francisco" \
  --country "United States" \
  --latitude 37.7749 \
  --longitude -122.4194 \
  --method 2 \
  --school 0 \
  --timezone "America/Los_Angeles"
Output: 
Configuration updated.

​
Viewing Configuration

roza config --show
Example Output: 
Current configuration:
  City: San Francisco
  Country: United States
  Latitude: 37.7749
  Longitude: -122.4194
  Method: 2
  School: 0
  Timezone: America/Los_Angeles
  First Roza Date: 2026-02-19

​
Updating Specific Settings

Update individual settings while keeping others: 
# Change only the calculation method
roza config --method 15

# Update city and country
roza config --city "Lahore" --country "Pakistan"

# Change timezone
roza config --timezone "Asia/Karachi"

​
Clearing Configuration

roza config --clear
Or use the reset command: 
roza reset
Both commands clear all saved settings.

​
Configuration Options

​
Location Settings

​
city
string
City name for prayer time calculationExamples:
  • "San Francisco"
  • "Lahore"
  • "Vancouver"
Set via:
roza config --city "San Francisco"
​
country
string
Country name for prayer time calculationExamples:
  • "United States"
  • "Pakistan"
  • "Canada"
Set via:
roza config --country "United States"
​
latitude
number
Geographic latitude (-90 to 90)Examples:
  • 37.7749 (San Francisco)
  • 31.5497 (Lahore)
  • 49.2827 (Vancouver)
Set via:
roza config --latitude 37.7749
​
longitude
number
Geographic longitude (-180 to 180)Examples:
  • -122.4194 (San Francisco)
  • 74.3436 (Lahore)
  • -123.1207 (Vancouver)
Set via:
roza config --longitude -122.4194

​
Prayer Calculation Settings

​
method
number
Calculation method ID (0-23)Determines how Fajr and Isha times are calculated. Each Islamic organization uses different angles.Common Methods:
  • 0 - Shia Ithna-Ashari
  • 1 - University of Islamic Sciences, Karachi
  • 2 - Islamic Society of North America (ISNA)
  • 3 - Muslim World League
  • 4 - Umm Al-Qura University, Makkah
  • 5 - Egyptian General Authority of Survey
  • 15 - Institute of Geophysics, University of Tehran
See Aladhan API Methods for complete list.Set via:
roza config --method 2
​
school
number
Juristic school for Asr calculation (0 or 1)Values:
  • 0 - Shafi, Maliki, Hanbali, Jafari (standard)
  • 1 - Hanafi (earlier Asr time)
Set via:
roza config --school 0
​
timezone
string
IANA timezone identifierEnsures accurate countdowns and times for your location.Examples:
  • America/Los_Angeles
  • America/New_York
  • Asia/Karachi
  • Asia/Dubai
  • Europe/London
  • America/Vancouver
Set via:
roza config --timezone "America/Los_Angeles"

​
Custom First Roza Date

By default, Ramadan CLI uses the Hijri calendar from the Aladhan API to determine Ramadan dates. You can override this with a custom first roza date.

​
Setting Custom Date

roza --first-roza-date 2026-02-19
This setting persists across runs: 
# Set custom date
roza --first-roza-date 2026-02-19

# Future runs use custom date
roza
roza --all
roza -n 15

​
Clearing Custom Date

Revert to API-provided Ramadan dates: 
roza --clear-first-roza-date

​
Date Format

Must use ISO 8601 date format: 
YYYY-MM-DD
Valid Examples:
  • 2026-02-19
  • 2026-03-01
  • 2027-02-08
Invalid Examples:
  • 19-02-2026 ❌
  • 02/19/2026 ❌
  • 2026/02/19 ❌

​
Use Cases

Your local community starts Ramadan based on local moonsighting:
# API says March 1, but local moonsighting confirms February 28
roza --first-roza-date 2026-02-28

​
How It Works

When a custom first roza date is set:
  1. Roza 1 = Your specified date
  2. Roza 2 = Your specified date + 1 day
  3. Roza 3 = Your specified date + 2 days
  4. … and so on for all 30 days
The CLI fetches prayer times for each calculated date from the API.
The custom date takes precedence over the API’s Hijri calendar. Make sure your date is accurate!

​
Country-Aware Recommendations

Ramadan CLI automatically recommends calculation methods and schools based on your country.

​
How Recommendations Work

roza "Lahore, Pakistan"
The CLI:
  1. Detects country is Pakistan
  2. Recommends method 1 (University of Islamic Sciences, Karachi)
  3. Recommends school 1 (Hanafi)
  4. Auto-applies recommendations if using default settings

​
When Recommendations Apply

Recommendations auto-apply when:
  • Using default/unset method or school
  • First-run interactive setup
  • No explicit config override
# Fresh setup, auto-applies Pakistan recommendations
roza "Lahore, Pakistan"
You can always override recommendations by explicitly setting your preferred method and school in the config.

​
Configuration Precedence

Ramadan CLI resolves configuration in this order (highest to lowest priority):
  1. Command-line arguments/flags 
    roza "San Francisco" --first-roza-date 2026-02-19
  2. Saved configuration 
    # Uses saved config
roza
  3. Auto-detected location 
    # No config, attempts IP geolocation
roza
  4. Interactive setup (if TTY available) 
    # Prompts for configuration
roza
  5. Error (if all else fails) 
    Could not detect location. Pass a city like `ramadan-cli "Lahore"`.

​
Examples

# Configuration exists
roza config --city "San Francisco"

# Uses saved config
roza

​
Configuration Storage

Configuration is stored in a local file on your system.

​
Default Location

  • macOS/Linux: ~/.config/ramadan-cli/config.json
  • Windows: %APPDATA%\ramadan-cli\config.json

​
Custom Storage Location

Override the storage directory: 
export RAMADAN_CLI_CONFIG_DIR="/custom/path"
roza config --show
Use Cases:
  • Testing with isolated configs
  • Multiple user profiles
  • Agent skill packages
  • CI/CD environments

​
What’s Stored

The config file contains: 
{
  "city": "San Francisco",
  "country": "United States",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "method": 2,
  "school": 0,
  "timezone": "America/Los_Angeles",
  "firstRozaDate": "2026-02-19"
}
The config file is created automatically. You don’t need to create or edit it manually.

​
Configuration for Different Use Cases

​
Personal Use

# First run - interactive setup
roza

# Check/update as needed
roza config --show
roza config --method 15

​
Scripts and Automation

# Non-interactive setup
roza config --city "San Francisco" --country "United States" --method 2

# Use JSON output
roza --json

​
CI/CD Environments

# Isolated config directory
export RAMADAN_CLI_CONFIG_DIR="$GITHUB_WORKSPACE/.ramadan-cli"

# Setup
roza config --city "Lahore" --country "Pakistan"

# Use in pipeline
roza --json | jq '.rows[0].iftar'

​
Status Bars (tmux, i3, waybar)

# Setup once
roza config --city "Vancouver" --country "Canada"

# Use in status bar config
roza -s

​
Coding Agents

# Agent-specific config directory
export RAMADAN_CLI_CONFIG_DIR="$HOME/.ai-agent/ramadan-cli"

# Setup for agent
roza config --city "Lahore" --country "Pakistan"

# Agent can call
roza --status
roza --json

​
Troubleshooting Configuration

​
Check Current Configuration

roza config --show

​
Test Different Locations

# Don't modify saved config, just test
roza "Lahore"
roza "San Francisco"
roza "Vancouver"

​
Reset and Reconfigure

# Clear everything
roza reset

# Start fresh
roza config --city "Your City" --country "Your Country"

​
Verify Configuration Works

# Check config
roza config --show

# Test main command
roza

# Test with all days
roza --all

​
Next Steps

Commands

Learn about all available commands

Flags and Options

Complete reference of command-line flags

Build docs developers (and LLMs) love

Get started for freeTalk to us