gem-hunter

Ramadan-first CLI for Sehar and Iftar timings in your terminal.

Built for humans and agents.

• 🌙 Ramadan-only output focused on Sehar/Iftar
• 📍 Auto first-run setup (city, country, method, school, timezone)
• 🌐 Auto-detect location via IP provider fallbacks
• 🧭 Auto-recommend method and school by country
• ⏱ Auto timezone detection for accurate countdowns
• ✨ Highlights current + next Sehar/Iftar with countdown
• 🗓 -a, --all for complete Ramadan month
• 🔢 -n, --number for a specific roza day
• 📟 -s, --status single-line next event for status bars and coding agents
• 🧪 Custom first roza override (--first-roza-date)
• 🧹 One-command reset (reset)

npx ramadan-cli

# or install globally and use alias
npm install -g ramadan-cli@latest
roza

Install this repo as an agent skill package:

npx skills add ahmadawais/ramadan-cli

# Show Sehar and Iftar times for today.
npx ramadan-cli
roza

# City examples.
npx ramadan-cli sf
npx ramadan-cli "San Francisco"
npx ramadan-cli lahore
npx ramadan-cli vancouver

# Full Ramadan month.
npx ramadan-cli sf --all
roza "San Francisco" -a

# Specific roza.
roza -n 10
roza "dera ghazi khan" -n 10

# Status line (next event only — for status bars, coding agents).
roza -s
roza --status
roza -s --city Lahore

# Set custom first roza date (stored).
roza --first-roza-date 2026-02-19

# Clear custom first roza date.
roza --clear-first-roza-date

# Reset saved config (location + settings + overrides).
roza reset

# Non-interactive config (no prompts).
ramadan-cli config --city "San Francisco" --country "United States" --method 2 --school 0 --timezone "America/Los_Angeles"
ramadan-cli config --show
ramadan-cli config --clear

ramadan-cli [city] [options]
ramadan-cli reset
ramadan-cli config [options]

Notes:

• No today subcommand; default run is today view.
• Passing a city is one-off and does not replace saved default location.

• Sehar = Fajr
• Iftar = Maghrib
• Time output is 12-hour (AM/PM)

Global/main command flags (ramadan-cli [city]):

Config flags (ramadan-cli config):

Reset command:

• ramadan-cli reset clears saved location, method, school, timezone, and custom first roza date.

• roza (same CLI)
• ramadan-cli
• ramzan
• ramazan
• ramadan

• stdout:
  • primary data output (table/plain/json)
  • version output (-v) prints version only
• stderr:
  • runtime and validation errors
• --json:
  • prints structured JSON only to stdout on success
  • prints structured JSON error payload to stderr on failure:
    • {"ok":false,"error":{"code":"...","message":"..."}}
• Exit codes:
  • 0 success
  • 1 runtime/validation/network/data failure
  • invalid usage parsing is handled by Commander defaults

• On first run (TTY), CLI launches interactive setup with Clack prompts.
• If --json or --status is used and no config exists, interactive setup is skipped.
• Config changes are explicit via config, reset, and first-roza flags.
• No stdin input contract yet. Input is args/flags only.

Data sources:

• flags/args (city, --first-roza-date, --clear-first-roza-date, mode flags)
• saved config (from first-run setup or ramadan-cli config)
• IP geolocation fallback when no saved config

Resolution behavior:

• One-off city arg/flag wins for that invocation but is not persisted.
• --clear-first-roza-date takes precedence over --first-roza-date if both are provided.
• Recommended method/school are auto-applied when using default/unset settings.
• RAMADAN_CLI_CONFIG_DIR controls where config is stored (useful for agent/test isolation).

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm lint

Powered by Aladhan Prayer Times API

MIT - Ahmad Awais