Ramadan CLI Agent Skill

Spec reference: skills/spec.md

Goal

Run, validate, and debug ramadan-cli safely and reproducibly.

What This CLI Is

ramadan-cli is a Ramadan-first CLI that shows:

• Sehar (Fajr) and Iftar (Maghrib) times
• today view, full month (-a), and specific roza (-n)
• first-run setup with saved config (city/country/method/school/timezone)

Primary user mode:

• Human-first interactive defaults
• Script-friendly deterministic modes via flags (--json, --plain, --status, config)

Command surface:

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

There is no today subcommand. ramadan-cli default run is the today view.

Basics Usage

ramadan-cli
ramadan-cli sf
ramadan-cli -a
ramadan-cli -n 10
ramadan-cli -s
ramadan-cli -s --city Lahore
ramadan-cli reset
ramadan-cli config --show

Alias support:

• roza (same CLI)
• sf city alias resolves to San Francisco

First run notes:

• Interactive setup appears on first run in TTY mode.
• --json skips interactive setup by design.
• One-off city input does not overwrite saved default location.

Non-interactive config:

ramadan-cli config --city "San Francisco" --country "United States" --latitude 37.7749 --longitude -122.4194 --method 2 --school 0 --timezone "America/Los_Angeles"
ramadan-cli config --show
ramadan-cli config --clear

First roza override controls:

ramadan-cli --first-roza-date 2026-02-18
ramadan-cli --clear-first-roza-date

Canonical Run Strategy

Prefer running the CLI command directly:

ramadan-cli --help
ramadan-cli
ramadan-cli sf -a
ramadan-cli -n 10
ramadan-cli reset

Use roza as an alias where desired. Use npx ramadan-cli when testing package-exec behavior. Use node dist/cli.js only as a local fallback during development/debugging.

I/O and Exit Contract

• stdout: main data output (table/plain/json), version output
• stderr: runtime failures and diagnostics
• --json: output JSON only to stdout on success
• --json failure payload on stderr: {"ok":false,"error":{"code":"...","message":"..."}}
• Exit code 0: success
• Exit code 1: runtime/API/validation failure
• Usage parse failures follow Commander defaults

Isolated Config Runs (Recommended for Agents)

Always isolate config in automation to avoid polluting user/global state:

TMP_CFG="/tmp/ramadan-cli-agent"
mkdir -p "$TMP_CFG"
RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli --help
RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli sf

Reset isolated state:

RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli reset

First-Run Setup Testing

Interactive setup requires TTY.

Manual TTY check:

RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli

Expected:

• Setup intro appears.
• Prompts for city/country/method/school/timezone.

Behavior Checks

Default location persistence

1. Run without city and complete setup.
2. Run with one-off city (ramadan-cli sf).
3. Run without city again.
4. Confirm default remains saved geodata/setup location (city query is one-off).

Roza modes

• ramadan-cli (today/default)
• ramadan-cli -a (all days)
• ramadan-cli -n 10 (specific roza)
• ramadan-cli --first-roza-date 2026-02-19
• ramadan-cli --clear-first-roza-date

Output modes

• ramadan-cli sf --json
• ramadan-cli sf --plain
• ramadan-cli sf -a (includes ← current / ← next row annotations)
• ramadan-cli -s (single line: Iftar in 2h 30m or Sehar in 8h 15m)
• ramadan-cli -s --city Lahore (status with one-off city)

Non-interactive readiness

• ramadan-cli config --show
• ramadan-cli config --clear
• ramadan-cli config --method 2 --school 0
• ramadan-cli --clear-first-roza-date
• ramadan-cli -s (always non-interactive; silent failure)