gem-hunter
Language: TypeScript
CLI to check Sehar and Iftar times in Ramadan anywhere in the world.
Ramadan-first CLI for Sehar and Iftar timings in your terminal.
Built for humans and agents.
-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--first-roza-date)reset)
npx ramadan-cli
# or install globally and use alias
npm install -g ramadan-cli@latest
rozaInstall 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:
today subcommand; default run is today view.Sehar = FajrIftar = MaghribAM/PM)Global/main command flags (ramadan-cli [city]):
| Flag | Type | Default | Behavior |
|---|---|---|---|
[city] |
string |
saved location | One-off lookup; does not overwrite saved default |
-c, --city <city> |
string |
none | Same as city arg |
-a, --all |
boolean |
false |
Show all Ramadan rows |
-n, --number <1-30> |
number |
none | Show specific roza |
-p, --plain |
boolean |
false |
Plain text output without ASCII banner |
-j, --json |
boolean |
false |
JSON-only output for scripts |
-s, --status |
boolean |
false |
Single-line next event output for status bars and coding agents |
--first-roza-date <YYYY-MM-DD> |
string |
stored/API | Persist custom first roza date |
--clear-first-roza-date |
boolean |
false |
Clear custom first roza date and use API Ramadan date |
-v, --version |
boolean |
n/a | Print version only |
-h, --help |
boolean |
n/a | Show help |
Config flags (ramadan-cli config):
| Flag | Type | Behavior |
|---|---|---|
--city <city> |
string |
Save city |
--country <country> |
string |
Save country |
--latitude <latitude> |
number |
Save latitude (-90..90) |
--longitude <longitude> |
number |
Save longitude (-180..180) |
--method <id> |
number |
Save method (0..23) |
--school <id> |
number |
Save school (0=Shafi, 1=Hanafi) |
--timezone <timezone> |
string |
Save timezone |
--show |
boolean |
Print saved config |
--clear |
boolean |
Clear saved config |
Reset command:
ramadan-cli reset clears saved location, method, school, timezone, and custom first roza date.roza (same CLI)ramadan-cliramzanramazanramadanstdout:
-v) prints version onlystderr:
--json:
stdout on successstderr on failure:
{"ok":false,"error":{"code":"...","message":"..."}}0 success1 runtime/validation/network/data failure--json or --status is used and no config exists, interactive setup is skipped.config, reset, and first-roza flags.Data sources:
city, --first-roza-date, --clear-first-roza-date, mode flags)ramadan-cli config)Resolution behavior:
--clear-first-roza-date takes precedence over --first-roza-date if both are provided.RAMADAN_CLI_CONFIG_DIR controls where config is stored (useful for agent/test isolation).pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm lintPowered by Aladhan Prayer Times API
MIT - Ahmad Awais