Configuration - Ramadan CLI

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:

Location Detection
- Automatically detects your location via IP geolocation
- Shows detected city and country
- Asks for confirmation
- Allows manual entry if auto-detection fails
Calculation Method
- Recommends a method based on your country
- Shows available methods (0-23)
- You can accept recommendation or choose manually
Juristic School
- Recommends school based on your country
- Options: Shafi (0) or Hanafi (1)
- Affects Asr prayer time calculation
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

Runs
Skips

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

Interactive setup skips when:

Configuration already exists
Using --json flag
Using --status flag
Not running in a TTY (scripts, pipes)
City is passed as argument or flag

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

Local Moonsighting
Different Calendar
Testing

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

Following a specific country’s calendar:

# Following Saudi Arabia's announcement
roza --first-roza-date 2026-03-01

Testing CLI with specific dates:

roza --first-roza-date 2026-02-19 --all

How It Works

When a custom first roza date is set:

Roza 1 = Your specified date
Roza 2 = Your specified date + 1 day
Roza 3 = Your specified date + 2 days
… 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:

Detects country is Pakistan
Recommends method 1 (University of Islamic Sciences, Karachi)
Recommends school 1 (Hanafi)
Auto-applies recommendations if using default settings

When Recommendations Apply

Auto-Applied
Not Applied

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"

Recommendations don’t apply when:

You’ve explicitly set method/school via config
Your saved config has specific values

# Your saved method 2 is preserved
roza config --method 2
roza "Lahore"  # Uses method 2, not Pakistan's method 1

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):

Command-line arguments/flags

roza "San Francisco" --first-roza-date 2026-02-19

Saved configuration
```
# Uses saved config
roza
```

Auto-detected location

# No config, attempts IP geolocation
roza

Interactive setup (if TTY available)
```
# Prompts for configuration
roza
```

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

Get Started

Usage

Features

Integration

​Overview

​First-Run Setup

​Interactive Setup Flow

​Auto-Detection

​When Interactive Setup Runs

​Non-Interactive Configuration

​Setting Configuration

​Viewing Configuration

​Updating Specific Settings

​Clearing Configuration

​Configuration Options

​Location Settings

​Prayer Calculation Settings

​Custom First Roza Date

​Setting Custom Date

​Clearing Custom Date

​Date Format

​Use Cases

​How It Works

​Country-Aware Recommendations

​How Recommendations Work

​When Recommendations Apply

​Configuration Precedence

​Examples

​Configuration Storage

​Default Location

​Custom Storage Location

​What’s Stored

​Configuration for Different Use Cases

​Personal Use

​Scripts and Automation

​CI/CD Environments

​Status Bars (tmux, i3, waybar)

​Coding Agents

​Troubleshooting Configuration

​Check Current Configuration

​Test Different Locations

​Reset and Reconfigure

​Verify Configuration Works

​Next Steps

Commands

Flags and Options

Overview

First-Run Setup

Interactive Setup Flow

Auto-Detection

When Interactive Setup Runs

Non-Interactive Configuration

Setting Configuration

Viewing Configuration

Updating Specific Settings

Clearing Configuration

Configuration Options

Location Settings

Prayer Calculation Settings

Custom First Roza Date

Setting Custom Date

Clearing Custom Date

Date Format

Use Cases

How It Works

Country-Aware Recommendations

How Recommendations Work

When Recommendations Apply

Configuration Precedence

Examples

Configuration Storage

Default Location

Custom Storage Location

What’s Stored

Configuration for Different Use Cases

Personal Use

Scripts and Automation

CI/CD Environments

Status Bars (tmux, i3, waybar)

Coding Agents

Troubleshooting Configuration

Check Current Configuration

Test Different Locations

Reset and Reconfigure

Verify Configuration Works

Next Steps