Flags and Options

Main Command Flags

Flags for the main ramadan-cli command (showing Sehar/Iftar timings).

City Selection

string

Positional argument for city name (one-off lookup)Type: stringDefault: Uses saved configuration or auto-detectsBehavior: Does not overwrite saved configuration. Only affects current run.Examples:

roza "San Francisco"
roza lahore
roza "Vancouver, Canada"

City Aliases:

sf → San Francisco

string

Flag alternative for specifying cityType: stringDefault: NoneBehavior: Same as positional city argumentExamples:

roza --city "San Francisco"
roza -c lahore

Display Modes

boolean

default:false

Show complete Ramadan month (all 30 days)Type: booleanDefault: falseExamples:

roza --all
roza -a
roza "Lahore" --all

Output: Table with all 30 roza days showing Sehar, Iftar, dates, and Hijri dates

Cannot be used with --number. Choose one display mode.

number

Show specific roza day (1-30)Type: number (integer)Range: 1 to 30Default: None (shows today by default)Validation: Must be an integer between 1 and 30, or you’ll get: Roza number must be between 1 and 30.Examples:

roza --number 15
roza -n 27
roza "Lahore" -n 1

Cannot be used with --all. Choose one display mode.

Output Formats

boolean

default:false

Plain text output without ASCII bannerType: booleanDefault: false (shows decorative banner)Behavior: Replaces ASCII art banner with simple “RAMADAN CLI” textExamples:

roza --plain
roza -p
roza "San Francisco" --plain --all

Use Cases:

Cleaner terminal output
Logging to files
Screen readers

boolean

default:false

JSON-only structured outputType: booleanDefault: falseBehavior:

Outputs structured JSON to stdout (success) or stderr (error)
Skips interactive setup prompts
Disables spinner and decorative output

Success Output:

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

Error Output (stderr):

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

Error Codes:

INVALID_FIRST_ROZA_DATE - Invalid date format
INVALID_FLAG_COMBINATION - Used --all and --number together
PRAYER_TIMES_FETCH_FAILED - API fetch error
RAMADAN_CALENDAR_FETCH_FAILED - Calendar fetch error
LOCATION_DETECTION_FAILED - Could not detect location
ROZA_NOT_FOUND - Invalid roza number
RAMADAN_CLI_ERROR - Generic error
UNKNOWN_ERROR - Unknown error

Examples:

roza --json
roza --json | jq '.rows[0].iftar'
roza "Lahore" --all --json

Use Cases:

Scripts and automation
CI/CD pipelines
Parsing with jq
Integration with other tools

boolean

default:false

Status line output (next event only)Type: booleanDefault: falseBehavior:

Outputs single line with next event and countdown
Silently fails on error (no output)
Skips interactive setup
Perfect for status bars

Output Examples:

Iftar in 3h 45m
Sehar in 8h 12m
Fast starts in 25m

Use Cases:

tmux status bar
i3 status bar
waybar
Coding agents
Shell prompts

Examples:

roza --status
roza -s
roza -s --city Lahore

tmux Example:

set -g status-right "#[fg=green]🌙 #(roza -s)#[default]"

i3blocks Example:

[ramadan]
command=roza -s
interval=60

Custom Date Override

string

Set and use a custom first roza dateType: string (ISO 8601 date)Format: YYYY-MM-DDDefault: Uses API-provided Ramadan date from Hijri calendarBehavior:

Persists across runs (saved to config)
Overrides API Hijri calendar
Calculates all 30 roza days from this start date

Validation: Must be valid ISO 8601 date or you’ll get: Invalid first roza date. Use YYYY-MM-DD.Examples:

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

Use Cases:

Local moonsighting differs from API
Following specific country’s calendar
Testing with specific dates

boolean

default:false

Clear custom first roza date and use API Ramadan dateType: booleanDefault: falseBehavior:

Removes saved custom first roza date
Reverts to API-provided Hijri calendar
Takes precedence over --first-roza-date if both provided

Examples:

roza --clear-first-roza-date

Use Cases:

Return to standard API dates
Remove test date override

Version and Help

boolean

Display version numberType: booleanOutput: Version string only to stdoutExamples:

roza --version
roza -v

Output:

2.0.0

boolean

Display help informationType: booleanOutput: Usage information and available flagsExamples:

roza --help
roza -h

Config Command Flags

Flags for the ramadan-cli config command (managing configuration).

Location Configuration

string

Save city name to configurationType: stringBehavior: Merges with existing config (doesn’t clear other values)Examples:

roza config --city "San Francisco"
roza config --city "Lahore"

string

Save country name to configurationType: stringBehavior: Merges with existing configExamples:

roza config --country "United States"
roza config --country "Pakistan"

number

Save latitude coordinate (-90 to 90)Type: numberRange: -90 to 90Validation: Must be between -90 and 90 or you’ll get: Invalid latitude.Examples:

roza config --latitude 37.7749
roza config --latitude 31.5497

number

Save longitude coordinate (-180 to 180)Type: numberRange: -180 to 180Validation: Must be between -180 and 180 or you’ll get: Invalid longitude.Examples:

roza config --longitude -122.4194
roza config --longitude 74.3436

Prayer Settings Configuration

number

Save calculation method (0-23)Type: number (integer)Range: 0 to 23Validation: Must be integer from 0 to 23 or you’ll get: Invalid method.Common Values:

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.Examples:

roza config --method 2
roza config --method 15

number

Save juristic school (0=Shafi, 1=Hanafi)Type: number (integer)Range: 0 or 1Validation: Must be 0 or 1 or you’ll get: Invalid school.Values:

0 - Shafi, Maliki, Hanbali, Jafari (standard Asr time)
1 - Hanafi (earlier Asr time)

Examples:

roza config --school 0
roza config --school 1

string

Save timezone identifierType: string (IANA timezone)Format: IANA timezone identifier (e.g., America/Los_Angeles)Common Values:

America/Los_Angeles
America/New_York
America/Chicago
America/Vancouver
Asia/Karachi
Asia/Dubai
Europe/London

Examples:

roza config --timezone "America/Los_Angeles"
roza config --timezone "Asia/Karachi"

Config Actions

boolean

default:false

Display current configurationType: booleanDefault: falseOutput:

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

Examples:

roza config --show

boolean

default:false

Clear all saved configurationType: booleanDefault: falseBehavior: Removes all saved settings (location, method, school, timezone, first roza date)Output:

Configuration cleared.

Examples:

roza config --clear

Equivalent to roza reset

Flag Combinations and Conflicts

Invalid Combinations

Cannot use together: --all and --numberThese flags are mutually exclusive. You must choose one display mode.

# ❌ Invalid
roza --all --number 15

# ✅ Valid
roza --all
roza --number 15

Error: Use either --all or --number, not both.

Flag Precedence

City
First Roza Date
Config

Both positional argument and flag can specify city:

# These are equivalent
roza "San Francisco"
roza --city "San Francisco"

If both provided, flag takes precedence:

# Uses Lahore (from flag)
roza "San Francisco" --city "Lahore"

--clear-first-roza-date takes precedence over --first-roza-date:

# Custom date is cleared (--clear wins)
roza --first-roza-date 2026-02-19 --clear-first-roza-date

In config command, last flag wins if duplicated:

# Uses method 15 (last one)
roza config --method 2 --method 15

Compatible Combinations

# City with display mode
roza "Lahore" --all
roza "San Francisco" --number 15

# City with output format
roza "Lahore" --json
roza "San Francisco" --plain

# Display mode with format
roza --all --json
roza --number 10 --plain

# City with custom date
roza "Lahore" --first-roza-date 2026-02-19
roza "San Francisco" --all --first-roza-date 2026-03-01

Flag Reference Tables

Main Command Flags

Flag	Short	Type	Default	Description
`[city]`	-	`string`	config/auto-detect	City for one-off lookup
`--city`	`-c`	`string`	none	City (flag alternative)
`--all`	`-a`	`boolean`	`false`	Show all 30 days
`--number`	`-n`	`number`	none	Show specific roza (1-30)
`--plain`	`-p`	`boolean`	`false`	Plain text output
`--json`	`-j`	`boolean`	`false`	JSON output
`--status`	`-s`	`boolean`	`false`	Status line output
`--first-roza-date`	-	`string`	API date	Custom first roza date (YYYY-MM-DD)
`--clear-first-roza-date`	-	`boolean`	`false`	Clear custom first roza date
`--version`	`-v`	`boolean`	-	Display version
`--help`	`-h`	`boolean`	-	Display help

Config Command Flags

Flag	Type	Range/Format	Description
`--city`	`string`	-	Save city name
`--country`	`string`	-	Save country name
`--latitude`	`number`	-90 to 90	Save latitude
`--longitude`	`number`	-180 to 180	Save longitude
`--method`	`number`	0 to 23	Save calculation method
`--school`	`number`	0 or 1	Save juristic school
`--timezone`	`string`	IANA timezone	Save timezone
`--show`	`boolean`	-	Display configuration
`--clear`	`boolean`	-	Clear configuration

Environment Variables

string

Override configuration directoryType: string (directory path)Default:

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

Examples:

export RAMADAN_CLI_CONFIG_DIR="/custom/path"
roza config --show

Use Cases:

Testing with isolated configs
Multiple user profiles
CI/CD environments
Agent skill packages

Examples by Use Case

Personal Daily Use

# Setup once
roza config --city "San Francisco" --country "United States"

# Daily usage
roza           # Today's timings
roza --all     # Full month view
roza -n 27     # Check Laylatul Qadr

Travelers

# Home config saved
roza config --city "San Francisco"

# Traveling to Lahore - one-off lookup
roza "Lahore"

# Back home - uses saved config
roza

Status Bars

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

# tmux status bar
roza -s

# waybar (in config.json)
"custom/ramadan": {
  "exec": "roza -s",
  "interval": 60
}

Scripts and Automation

# Non-interactive setup
roza config --city "Lahore" --country "Pakistan" --method 1

# JSON output for parsing
IFTAR_TIME=$(roza --json | jq -r '.rows[0].iftar')
echo "Iftar: $IFTAR_TIME"

# Check specific day
roza -n 15 --json | jq '.rows[0]'

CI/CD Pipelines

# Isolated config
export RAMADAN_CLI_CONFIG_DIR="$CI_PROJECT_DIR/.ramadan"

# Setup
roza config --city "San Francisco" --country "United States"

# Use in pipeline
roza --json > timings.json

Testing Different Dates

# Test with custom start date
roza --first-roza-date 2026-02-19 --all

# Check specific day with custom date
roza -n 27 --first-roza-date 2026-02-19

# Clear and revert to API dates
roza --clear-first-roza-date

Multiple Locations

# Check multiple cities without changing config
roza "San Francisco"
roza "Lahore"
roza "Vancouver"
roza "Dubai"

# Compare in JSON
roza "San Francisco" --json > sf.json
roza "Lahore" --json > lahore.json

Get Started

Usage

Features

Integration

Main Command Flags

City Selection

Display Modes

Output Formats

Custom Date Override

Version and Help

Config Command Flags

Location Configuration

Prayer Settings Configuration

Config Actions

Flag Combinations and Conflicts

Invalid Combinations

Flag Precedence

Compatible Combinations

Flag Reference Tables

Main Command Flags

Config Command Flags

Environment Variables

Examples by Use Case

Personal Daily Use

Travelers

Status Bars

Scripts and Automation

CI/CD Pipelines

Testing Different Dates

Multiple Locations

Next Steps

Basic Usage

Configuration

​Main Command Flags

​City Selection

​Display Modes

​Output Formats

​Custom Date Override

​Version and Help

​Config Command Flags

​Location Configuration

​Prayer Settings Configuration

​Config Actions

​Flag Combinations and Conflicts

​Invalid Combinations

​Flag Precedence

​Compatible Combinations

​Flag Reference Tables

​Main Command Flags

​Config Command Flags

​Environment Variables

​Examples by Use Case

​Personal Daily Use

​Travelers

​Status Bars

​Scripts and Automation

​CI/CD Pipelines

​Testing Different Dates

​Multiple Locations

​Next Steps

Basic Usage

Configuration

Main Command Flags

City Selection

Display Modes

Output Formats

Custom Date Override

Version and Help

Config Command Flags

Location Configuration

Prayer Settings Configuration

Config Actions

Flag Combinations and Conflicts

Invalid Combinations

Flag Precedence

Compatible Combinations

Flag Reference Tables

Main Command Flags

Config Command Flags

Environment Variables

Examples by Use Case

Personal Daily Use

Travelers

Status Bars

Scripts and Automation

CI/CD Pipelines

Testing Different Dates

Multiple Locations

Next Steps