ramadan-cli narrows prayer times down to Sehar and Iftar

A terminal that only knows about Sehar and Iftar

Most prayer time apps answer five or six prayers a day, and their screens are built for scrolling. ramadan-cli takes the opposite bet. Its stated focus is Ramadan-only output limited to Sehar and Iftar, with the two names mapped in the documentation to Fajr and Maghrib respectively. Time output is rendered in 12-hour AM/PM format, and the same run can be produced as a table, as plain text without the ASCII banner, or as JSON.

That narrowness is the design. A developer who wants to know when to stop eating in the morning and when to break the fast after sunset gets two facts and a countdown, not a dashboard of sunrise, dhuhr, asr and maghrib angles. The tool is also aimed squarely at automation: the README frames it as built for humans and agents, and one flag exists purely so a shell prompt bar or a scripted agent can poll it without parsing a table.

The audience is therefore split. For a person, ramadan-cli is a fast lookup you can type from any directory. For an agent, it is a callable that returns a predictable single line or a structured document. The project targets a narrow religious calendar rather than general religious software, and every feature in the flag list serves that scope.

How ramadan-cli resolves a city, a method and a school

Timing data comes from the Aladhan Prayer Times API, so the tool is a client rather than an astronomy engine. What ramadan-cli contributes is the layer that decides what to ask for and how to display the answer.

Three sources feed that decision. Flags and arguments come first, including a city argument, the mode flags and the first roza date overrides. Saved configuration comes second, created either by the interactive first-run setup or by an explicit config command. When neither exists, an IP geolocation fallback is used, and the README describes location detection as working through IP provider fallbacks.

On first run in a TTY, the tool launches interactive setup using Clack prompts, collecting city, country, method, school and timezone. The same setup recommends a calculation method and a school for the country it detects, and those recommended values are auto-applied when settings are unset. Timezone detection exists so countdowns stay accurate.

The precedence rules are deliberately explicit. A one-off city argument wins for that single invocation but is never written to disk, and the documentation is blunt that passing a city does not replace your saved default location. If both a custom first roza date and a flag to clear it are given, the clear flag wins.

Install with npx and run the first lookup

The quickest path needs no install step. The documented commands are:

npx ramadan-cli

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

Running npx ramadan-cli without arguments shows Sehar and Iftar times for today. On a first run with no saved config and a real terminal, you should expect the interactive setup to ask for your city, country, calculation method, school and timezone before any times appear.

Cities can be passed by name for a one-off check, and the tool accepts partial names such as a short code or a lowercase city:

npx ramadan-cli sf
npx ramadan-cli "San Francisco"
npx ramadan-cli lahore
npx ramadan-cli vancouver

Because a city argument is not persisted, these lookups leave your saved location untouched. If you want a global install, note that the package registers several binaries, so the same tool answers to ramzan, ramazan, ramadan and roza as well as ramadan-cli.

For agent runtimes the project documents a separate packaging route, treating the repository as a skill package:

npx skills add ahmadawais/ramadan-cli

Output modes built for status bars and coding agents

Two flags exist for machines rather than people. The status flag prints a single line naming the next event, which the documentation positions for status bars and coding agents, and the json flag prints structured JSON only to standard output on success.

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

Failure handling is also machine oriented. On an error, the json mode writes a structured payload to standard error in the shape {"ok":false,"error":{"code":"...","message":"..."}}, while runtime and validation errors go to standard error in normal mode. The exit code contract is small: 0 for success and 1 for runtime, validation, network or data failure, with invalid usage parsing left to the defaults of the Commander parser.

Two interactive prompts are deliberately suppressed when scripting: the first-run setup is skipped if json or status is used and no configuration exists yet. That matters for a CI job or a fresh container where no config file exists yet, since the command returns a result rather than hanging on a prompt.

For humans reading a whole month, the all flag expands the output to every Ramadan row, and the number flag pins a single roza day:

npx ramadan-cli sf --all
roza "San Francisco" -a
roza -n 10
roza "dera ghazi khan" -n 10

The plain flag strips the ASCII banner, which is the variant to prefer when you are piping the output somewhere.

The config file that holds your saved location

Settings live in a local config store written through the conf package, and the config subcommand is the explicit way to change them. Everything can be set without touching the interactive setup:

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

The saved fields are city, country, latitude and longitude, calculation method, school and timezone. The method accepts a numeric id in the 0 to 23 range, and the school flag uses 0 for Shafi and 1 for Hanafi, so the configuration is stored in the same numeric vocabulary the API expects rather than in names.

Two location inputs are stored as well. The latitude flag accepts values from -90 to 90 and the longitude flag from -180 to 180, which lets you pin coordinates directly when a city name is ambiguous. The custom first roza date is stored separately and can be set or removed at any time:

roza --first-roza-date 2026-02-19
roza --clear-first-roza-date
roza reset

The reset command clears the saved location, method, school, timezone and the custom first roza date in one go, which is the fastest way out of a bad first-run setup. The environment variable RAMADAN_CLI_CONFIG_DIR redirects where the config is stored, a detail that matters if you want an isolated setup for a test or for an agent session rather than sharing your personal location settings.

The API response is the weak link, and the override flags exist for that

ramadan-cli does no astronomical computation itself. Every time it prints comes from the Aladhan Prayer Times API, so a network outage, a rate limit or a change on the service side turns into a failed lookup with exit code 1. There is no documented offline mode and no cache fallback, which is the main reason a project with an installed global binary still depends on connectivity at run time.

The API also sets the calendar. When no override is present, the tool uses the Ramadan date returned by the service, and the calculation method and school you chose decide which of the service's variants you see. When a local mosque disagrees, the first roza date flag lets you override the calendar start for your own runs, and clearing it returns you to the API value.

Two smaller constraints are documented plainly. There is no today subcommand, so the default run is the today view and the interface stays short. There is also no stdin contract yet, meaning every input arrives as an argument or a flag, so you cannot pipe a date or a location into the tool. The command surface is limited to three shapes: the main city command, reset and config.

Calling the Aladhan API yourself instead of installing a CLI

The obvious alternative is to skip the package and query the Aladhan Prayer Times API from a script you write. The difference in approach is real and cuts both ways.

Going direct means your script owns the request, the response parsing and the date arithmetic, and you get access to whatever the API returns rather than the subset the CLI chooses to show. ramadan-cli shows only Sehar and Iftar, so a general prayer time client is out of reach with it, and you would need your own formatting for every output mode the tool provides for free.

Staying with the CLI means accepting its dependencies, Commander, Zod, conf, Clack, ora and picocolors, and its runtime floor of Node 20 or newer. In exchange you get a resolved location, a country-aware method and school recommendation, saved settings, an IP fallback for the no-config case, a JSON contract with a documented error shape, and a single-line status output that is already formatted for a prompt.

For a one-off lookup in a script that already has an HTTP client and knows its coordinates, the direct call is less machinery. For a long-lived shell setup, a status bar, or an agent that needs a stable contract, the CLI does the resolution work you would otherwise write and maintain yourself.

Maintenance signals from the release and push history

The repository is not archived. The last push was on 2026-06-08, and the recent release tags are 6.2.0 on 2026-03-10, 6.1.0 on 2026-02-18 and 6.0.1 on 2026-02-18. The published package version in package.json is 6.2.0, matching the newest tag.

Upgrading is a normal npm dependency update. The project is built with TypeScript, bundled with tsup, tested with vitest, linted with biome and typed with tsc, and it pins pnpm as its package manager at version 10.5.0. The documented development commands are:

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm lint

The license is MIT, which in practice means you can run the tool, modify it and ship it in your own setup without per-use licensing negotiation. That is the practical point for teams: no license keys, no per-machine activation, and the source is available for auditing the calculation method behind a given answer. What the MIT grant does not do is certify the accuracy of the timings, which still rests with the API and the method and school you select.

Editorial conclusion

ramadan-cli fits developers and agent runtimes that want two Ramadan events on demand without opening a browser, and it costs nothing to try since the first run works through npx. It is the wrong choice for anyone who needs the other four daily prayers, for offline use, or for a schedule that must be audited against a locally computed astronomical table. Check first that the Aladhan API answer matches the method and school your local mosque uses, then verify the saved city, timezone and method with the config command before trusting a countdown.

Frequently asked questions

Official sources

1. ahmadawais/ramadan-cli on GitHub
2. License: MIT
3. Project website
4. README
5. Releases