Commands

Complete reference for all Ramadan CLI commands

Main Command

The main command displays Sehar and Iftar timings for Ramadan.

Syntax

ramadan-cli [city] [options]
roza [city] [options]

Arguments

city · string

City name for one-off lookup. Does not overwrite saved configuration.

Examples:

• "San Francisco"
• "sf" (alias for San Francisco)
• "Lahore"
• "Vancouver"
• "San Francisco, United States" (city, country format)

Behavior

By default (no flags), shows today’s Sehar and Iftar timing:

roza

On first run with a TTY, the CLI launches an interactive setup to configure your location, calculation method, and school.

Options

See Flags and Options for complete flag documentation.

Examples

Default (Today)

# Show today's timings
roza

---

Reset Command

Clear all saved Ramadan CLI configuration.

Syntax

ramadan-cli reset
roza reset

What It Clears

The reset command removes:

• Saved location (city, country, latitude, longitude)
• Saved prayer settings (method, school, timezone)
• Custom first roza date override

Example

roza reset

Output:

Configuration reset.

After reset, the next run will:

1. Attempt auto-detection via IP geolocation
2. Or prompt for interactive setup (if TTY available)
3. Or require you to pass a city explicitly

When to Use Reset

Traveling

Reset when you’ve moved to a new location and want to reconfigure:

roza reset
roza  # Will prompt for new location

Testing

Reset to test first-run setup experience:

roza reset
roza --city "Lahore"  # One-off lookup

Fixing Issues

Reset if your saved config is causing issues:

roza reset
roza config --city "San Francisco" --country "United States"

Reset is permanent. You’ll need to reconfigure your location after using this command.

---

Config Command

Manage saved configuration non-interactively.

Syntax

ramadan-cli config [options]
roza config [options]

Use Cases

• Set configuration without interactive prompts
• Update specific settings while keeping others
• View current configuration
• Clear all settings
• Useful for scripts and automation

Setting Configuration

Update one or more configuration values:

# Set location
roza config --city "San Francisco" --country "United States"

# Set coordinates
roza config --latitude 37.7749 --longitude -122.4194

# Set calculation method and school
roza config --method 2 --school 0

# Set timezone
roza config --timezone "America/Los_Angeles"

# Set multiple values at once
roza config --city "Lahore" --country "Pakistan" --method 1 --school 1

Viewing Configuration

Display your current saved settings:

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

Clearing Configuration

Remove all saved settings:

roza config --clear

Output:

Configuration cleared.

This is equivalent to roza reset.

Options

--city · string

Save city name

Example: --city "San Francisco"

--country · string

Save country name

Example: --country "United States"

--latitude · number

Save latitude coordinate (-90 to 90)

Example: --latitude 37.7749

Validation: Must be between -90 and 90

--longitude · number

Save longitude coordinate (-180 to 180)

Example: --longitude -122.4194

Validation: Must be between -180 and 180

--method · number

Save calculation method (0-23)

Example: --method 2

Validation: Must be an integer from 0 to 23

See Aladhan API Methods for method IDs.

--school · number

Save juristic school for Asr calculation

Values:

• 0 - Shafi, Maliki, Hanbali, Jafari
• 1 - Hanafi

Example: --school 0

Validation: Must be 0 or 1

--timezone · string

Save timezone identifier

Example: --timezone "America/Los_Angeles"

Use standard IANA timezone identifiers like:

• America/Los_Angeles
• Asia/Karachi
• America/Vancouver
• Europe/London

--show · boolean

Display current configuration

Example: roza config --show

--clear · boolean

Clear all saved configuration

Example: roza config --clear

Configuration Behavior

Merging Updates

When you update config values, they merge with existing settings:

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

# Later update - only changes method, keeps city and country
roza config --method 15

# View merged result
roza config --show
# City: San Francisco (kept)
# Country: United States (kept)
# Method: 15 (updated)

No Updates Provided

If you run config without any update flags:

roza config

Output:

No config updates provided. Use `ramadan-cli config --show` to inspect.

Validation Errors

The config command validates all inputs:

Invalid Latitude

$ roza config --latitude 100
Error: Invalid latitude.

Examples

Complete Setup

# Configure everything at once
roza config \
  --city "San Francisco" \
  --country "United States" \
  --latitude 37.7749 \
  --longitude -122.4194 \
  --method 2 \
  --school 0 \
  --timezone "America/Los_Angeles"

Update Location

# Just update your city
roza config --city "Vancouver" --country "Canada"

Update Method

# Change calculation method
roza config --method 1

View & Clear

# Check current settings
roza config --show

# Start fresh
roza config --clear

Comparison: Interactive vs Config Command

Feature	First-Run Interactive	config Command
Prompts	Yes, uses Clack prompts	No prompts
When	First run (TTY only)	Anytime
Input	Interactive selections	Command-line flags
Use Case	Initial setup	Scripts, updates, automation
Location Detection	Offers auto-detect	Must provide values
Recommendations	Suggests method/school	You set explicitly

Use interactive setup for first-time configuration. Use config command for scripted setups or quick updates.

Environment Variable

Control where config is stored:

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

Useful for:

• Testing with isolated configs
• Agent skill packages
• Multiple user profiles

---

Command Summary

Command	Purpose	Interactive
roza	Show Sehar/Iftar timings	Yes (first run)
roza reset	Clear all configuration	No
roza config	Manage config non-interactively	No

Next Steps

Flags and Options

Complete reference of all command-line flags

Configuration

Learn about interactive setup and config management