https://github.com/ahmadawais/ramadan-cli
CLI to check Sehar and Iftar times in Ramadan anywhere in the world.
https://github.com/ahmadawais/ramadan-cli
cli ramadan
Last synced: 4 months ago
JSON representation
CLI to check Sehar and Iftar times in Ramadan anywhere in the world.
- Host: GitHub
- URL: https://github.com/ahmadawais/ramadan-cli
- Owner: ahmadawais
- License: mit
- Created: 2020-04-24T18:48:50.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2026-02-18T15:42:15.000Z (4 months ago)
- Last Synced: 2026-02-18T18:25:57.789Z (4 months ago)
- Topics: cli, ramadan
- Language: TypeScript
- Homepage: https://x.com/MrAhmadAwais/
- Size: 16.5 MB
- Stars: 206
- Watchers: 1
- Forks: 23
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Contributing: contributing.md
- Funding: .github/funding.yml
- License: license
- Code of conduct: code-of-conduct.md
Awesome Lists containing this project
README
[](https://x.com/MrAhmadAwais/)
# ramadan-cli 🌙
[](https://www.npmjs.com/package/ramadan-cli)
[](https://NodeCLI.com/?utm_source=FOSS)
[](https://x.com/mrahmadawais/)
> Ramadan-first CLI for Sehar and Iftar timings in your terminal.
Built for humans and agents.
## Why You'll Like It
- 🌙 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
- 🧪 Custom first roza override (`--first-roza-date`)
- 🧹 One-command reset (`reset`)
[](https://x.com/MrAhmadAwais/)
## Install
```sh
npx ramadan-cli
# or install globally and use alias
npm install -g ramadan-cli@latest
roza
```
## Agent Usage
Install this repo as an agent skill package:
```sh
npx skills add ahmadawais/ramadan-cli
```
## Usage
```sh
# 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
# 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
```
## CLI Surface
```sh
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.
## Output Semantics
- `Sehar` = `Fajr`
- `Iftar` = `Maghrib`
- Time output is 12-hour (`AM/PM`)
## Flags and Arguments
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 ` | `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 |
| `--first-roza-date ` | `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 ` | `string` | Save city |
| `--country ` | `string` | Save country |
| `--latitude ` | `number` | Save latitude (`-90..90`) |
| `--longitude ` | `number` | Save longitude (`-180..180`) |
| `--method ` | `number` | Save method (`0..23`) |
| `--school ` | `number` | Save school (`0=Shafi`, `1=Hanafi`) |
| `--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.
## Aliases
- `roza` (same CLI)
- `ramadan-cli`
- `ramzan`
- `ramazan`
- `ramadan`
## I/O Contract
- `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
## Interactivity and Safety
- On first run (TTY), CLI launches interactive setup with Clack prompts.
- If `--json` 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.
## Config and Precedence
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).
## Development
```sh
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm lint
```
## API
Powered by [Aladhan Prayer Times API](https://aladhan.com/prayer-times-api)
## License
MIT - [Ahmad Awais](https://x.com/MrAhmadAwais)