siyam-cli

صيام · The Ramadan Terminal Companion

◈━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━◈
┃   ◆  ◇  ◆   s i y a m - c l i   ◆  ◇  ◆   ┃
┃        صيام  ·  Ramadan Terminal          ┃
◈━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━◈

A developer-first, terminal-native Ramadan companion. Get Sehar (Fajr) and Iftar (Maghrib) prayer times instantly from the command line — no browser, no app, no distractions.

Install

npm i -g siyam-cli

Requires Node.js >= 18.

Quick Start

# First run launches interactive setup
siyam

# Or configure non-interactively
siyam config --city Dubai --country "United Arab Emirates" --method 8 --school 1 --timezone "Asia/Dubai"

# Then just run
siyam

Aliases

All four binary names are registered and work identically:

siyam    # primary
roza     # alias
sehar    # alias
iftar    # alias

Commands

Default (today view)

siyam                    # Rich table with banner, times, countdown
siyam Dubai              # Override city for this run
siyam --plain            # Plain key=value output (no ANSI)
siyam --json             # Structured JSON to stdout
siyam --status           # Single line: "Iftar in 2h 30m"
siyam --all              # Full 30-day Ramadan table
siyam -n 27              # Show Roza 27 specifically

Config

siyam config --show      # Print current config as JSON
siyam config --clear     # Delete config file
siyam config --city Karachi --country Pakistan

Reset

siyam reset              # Clear config and re-run interactive setup

Flags

| Flag | Short | Description | |------|-------|-------------| | --all | -a | Show all 30 days of Ramadan | | --number <n> | -n | Show times for a specific roza number | | --plain | -p | Plain text output (no ANSI codes) | | --json | -j | JSON output to stdout | | --status | -s | Single-line status for shell integrations | | --city <name> | | City name override | | --first-roza-date <date> | | Custom Ramadan start date (YYYY-MM-DD) | | --clear-first-roza-date | | Revert to Hijri-based roza numbering | | --version | -V | Show version | | --help | -h | Show help |

Output Modes

Rich (default)

Displays the Islamic geometric banner, metadata (city, method, roza), prayer times, and a countdown to the next event.

Plain (--plain)

city=Dubai
country=United Arab Emirates
date=2026-02-19
sehar=05:27
iftar=18:15
roza=2
is_ramadan=true
next_event=iftar
countdown=3h 12m

JSON (--json)

{
  "ok": true,
  "data": {
    "city": "Dubai",
    "country": "United Arab Emirates",
    "date": "2026-02-19",
    "hijriDate": "2 Ramaḍān 1447",
    "sehar": "05:27",
    "iftar": "18:15",
    "roza": 2,
    "isRamadan": true,
    "nextEvent": "iftar",
    "countdown": "3h 12m"
  }
}

Errors in JSON mode are written to stderr:

{ "ok": false, "error": { "code": "NETWORK_ERROR", "message": "..." } }

Status (--status)

Iftar in 2h 30m

Shell Integrations

tmux status bar

Add to ~/.tmux.conf:

set -g status-right '#(siyam --status)'
set -g status-interval 60

Zsh prompt

Add to ~/.zshrc:

RPROMPT='$(siyam --status 2>/dev/null)'

Polybar

[module/siyam]
type = custom/script
exec = siyam --status
interval = 60

Roza Numbering

By default, roza number is computed from the Hijri calendar (Aladhan API metadata). For regions where Ramadan starts on a different date:

siyam --first-roza-date 2026-02-28    # Set custom start
siyam --clear-first-roza-date          # Revert to Hijri

Config Location

Config is stored at ~/.config/siyam-cli/config.json (or $XDG_CONFIG_HOME/siyam-cli/config.json).

Override with the SIYAM_CLI_CONFIG_DIR environment variable:

SIYAM_CLI_CONFIG_DIR=/tmp/test siyam --json

Data Source

Prayer times are fetched from the Aladhan Prayer Times API — free, no auth required. Supports multiple calculation methods and juristic schools.

Development

pnpm install
pnpm build          # Build with tsup
pnpm dev            # Watch mode
pnpm test           # Run tests
pnpm test:coverage  # Run tests with coverage
pnpm lint           # Type check

License

MIT