Status Line Mode - Ramadan CLI

Overview

The --status (or -s) flag provides a single-line output showing the next upcoming prayer event with a countdown. This mode is perfect for status bars, coding agents, and minimal displays.

Basic Usage

ramadan-cli --status
ramadan-cli -s

Example Output:

Iftar in 2h 30m

Status mode is completely non-interactive and silent on failure. It’s designed to never interrupt your workflow.

Output Format

The status line shows the next prayer event with time remaining:

{Event} in {Countdown}

Possible Event Labels

Regular Events
Edge Cases

Label	Meaning
`Sehar`	Sehar window (Fajr) is upcoming
`Fast starts`	Roza (fast) is about to begin
`Iftar`	Iftar (Maghrib) is upcoming

Label	When It Appears
`First Sehar`	Before Ramadan starts (shows first Sehar)
`Sehar`	Next day’s Sehar (after Iftar)

Countdown Format

Hours and Minutes

2h 30m

When more than 1 hour remains

Minutes Only

45m

When less than 1 hour remains

Final Minutes

5m

When very close to the event

Status Bar Integration

tmux

Add Ramadan timings to your tmux status bar:

# Add to your tmux configuration
set -g status-right '#(ramadan-cli -s) | %H:%M'
set -g status-interval 60

Set status-interval to 60 seconds to update the countdown every minute.

Polybar

Integrate with Polybar status bar:

[module/ramadan]
type = custom/script
exec = ramadan-cli -s
interval = 60
format = 🌙 <label>
format-foreground = #81F096

i3status

Add to i3status configuration:

order += "tztime ramadan"

tztime ramadan {
    format = "🌙 %Y-%m-%d %H:%M:%S"
    hide_if_equals_localtime = true
}

Waybar

For Wayland users with Waybar:

{
  "custom/ramadan": {
    "exec": "ramadan-cli -s",
    "interval": 60,
    "format": "🌙 {}",
    "on-click": "alacritty -e ramadan-cli",
    "tooltip": false
  }
}

Terminal Integration

Shell Prompt (PS1)

Add to your shell prompt:

# Add Ramadan timing to prompt
export PS1='\[\033[32m\]$(ramadan-cli -s 2>/dev/null)\[\033[0m\] \w $ '

Shell prompts execute on every command. Consider caching to avoid repeated CLI calls:

function _ramadan_cached() {
    local cache_file="/tmp/ramadan-status-$USER"
    if [ ! -f "$cache_file" ] || [ $(find "$cache_file" -mmin +1) ]; then
        ramadan-cli -s 2>/dev/null > "$cache_file"
    fi
    cat "$cache_file" 2>/dev/null
}

export PS1='$(\[\033[32m\]_ramadan_cached\[\033[0m\]) \w $ '

Coding Agent Integration

VS Code Status Bar

Create a VS Code extension:

const vscode = require('vscode');
const { exec } = require('child_process');

let statusBarItem;

function activate(context) {
    statusBarItem = vscode.window.createStatusBarItem(
        vscode.StatusBarAlignment.Right,
        100
    );
    statusBarItem.text = '🌙 Loading...';
    statusBarItem.show();
    
    updateStatus();
    setInterval(updateStatus, 60000); // Update every minute
}

function updateStatus() {
    exec('ramadan-cli -s', (error, stdout, stderr) => {
        if (!error && stdout) {
            statusBarItem.text = `🌙 ${stdout.trim()}`;
        } else {
            statusBarItem.text = '🌙 Ramadan';
        }
    });
}

module.exports = { activate };

JetBrains IDEs

For IntelliJ, PyCharm, WebStorm, etc.:

import com.intellij.openapi.project.Project
import com.intellij.openapi.wm.StatusBar
import com.intellij.openapi.wm.StatusBarWidget
import java.io.BufferedReader
import java.io.InputStreamReader

class RamadanStatusWidget(project: Project) : StatusBarWidget {
    override fun ID(): String = "RamadanStatus"
    
    override fun getPresentation(): StatusBarWidget.WidgetPresentation {
        return object : StatusBarWidget.TextPresentation {
            override fun getText(): String {
                return try {
                    val process = Runtime.getRuntime().exec("ramadan-cli -s")
                    val reader = BufferedReader(InputStreamReader(process.inputStream))
                    val output = reader.readLine() ?: "Ramadan"
                    "🌙 $output"
                } catch (e: Exception) {
                    "🌙 Ramadan"
                }
            }
            
            override fun getTooltipText(): String = "Ramadan prayer times"
        }
    }
}

Neovim/Vim Statusline

" In .vimrc or init.vim
function! RamadanStatus()
    let status = system('ramadan-cli -s 2>/dev/null')
    return substitute(status, '\n', '', 'g')
endfunction

set statusline=%{RamadanStatus()}\ %f\ %m\ %r

Location Override

Use --city to query a different location in status mode:

ramadan-cli -s --city Lahore
ramadan-cli -s --city "Dubai, UAE"
ramadan-cli -s --city sf

One-off city queries don’t overwrite your saved default location.

Error Handling

Silent Failure Behavior

Status mode fails silently by design:

# No output on error
ramadan-cli -s
echo $?  # Exit code still returns 0

This prevents error messages from cluttering your status bar.

Fallback Display

Provide a fallback for when status mode fails:

RAMADAN_STATUS=$(ramadan-cli -s 2>/dev/null)
if [ -z "$RAMADAN_STATUS" ]; then
    echo "Ramadan"
else
    echo "$RAMADAN_STATUS"
fi

Performance Optimization

Caching Strategy

Since countdowns change every minute, cache for 60 seconds:

#!/bin/bash

CACHE_FILE="/tmp/ramadan-status-cache"
CACHE_TIME=60  # seconds

if [ -f "$CACHE_FILE" ]; then
    AGE=$(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE")))
    if [ $AGE -lt $CACHE_TIME ]; then
        cat "$CACHE_FILE"
        exit 0
    fi
fi

# Update cache
ramadan-cli -s 2>/dev/null | tee "$CACHE_FILE"

Background Updates

Use a background process to keep the cache warm:

#!/bin/bash

# Start in background
(
    while true; do
        ramadan-cli -s > /tmp/ramadan-status-cache 2>/dev/null
        sleep 60
    done
) &

echo $! > /tmp/ramadan-status-pid

Complete Examples

Minimal tmux Setup

# ~/.tmux.conf
set -g status-right '🌙 #(ramadan-cli -s 2>/dev/null || echo "Ramadan") | %H:%M '
set -g status-interval 60

[module/ramadan]
type = custom/script
exec = ramadan-cli -s 2>/dev/null || echo "Ramadan"
interval = 60
format = <label>
format-prefix = "🌙 "
format-prefix-foreground = #81F096
click-left = notify-send "Ramadan" "$(ramadan-cli)"

#!/bin/bash
# ramadan-widget.sh

set -euo pipefail

CACHE="/tmp/ramadan-widget-$USER"

# Check cache (1 minute)
if [ -f "$CACHE" ]; then
    if [ $(($(date +%s) - $(stat -c %Y "$CACHE"))) -lt 60 ]; then
        cat "$CACHE"
        exit 0
    fi
fi

# Update and cache
OUTPUT=$(ramadan-cli -s 2>/dev/null || echo "Ramadan")
echo "$OUTPUT" > "$CACHE"
echo "$OUTPUT"

Testing

Test Basic Output

ramadan-cli -s

Should output a single line with no errors.

Test with Location

ramadan-cli -s --city "New York"
ramadan-cli -s --city lahore

Test Error Handling

# Should produce no output
ramadan-cli -s --city "InvalidCity12345"
echo $?  # Should be 0

Test in Status Bar

Add to your status bar config and reload:

# For tmux
tmux source-file ~/.tmux.conf

# For polybar
pkill -USR1 polybar

Troubleshooting

No output appears

Check if ramadan-cli is installed: which ramadan-cli
Test manually: ramadan-cli -s
Check exit code: ramadan-cli -s; echo $?
Verify PATH in status bar environment

Output is too long

The status line is designed to be concise. Maximum length is around 20-30 characters:

Iftar in 12h 45m  # Longest typical output

If truncated, adjust your status bar width settings.

Status doesn't update

Check refresh interval in your status bar config
Verify the CLI is being called each time
Try clearing any caches: rm /tmp/ramadan-*

Wrong timezone displayed

Configure timezone explicitly:

ramadan-cli config --timezone "America/New_York"

Then test:

ramadan-cli -s

Best Practices

Cache Aggressively

Update every 60 seconds, not on every display refresh

Handle Failures

Always provide a fallback display value

Suppress Errors

Redirect stderr to /dev/null in status bars

Keep It Simple

Status line is for quick glances, not detailed info

JSON Output

Structured output for advanced integrations

Agent Usage

Using ramadan-cli in automated workflows

Get Started

Usage

Features

Integration

​Overview

​Basic Usage

​Output Format

​Possible Event Labels

​Countdown Format

Hours and Minutes

Minutes Only

Final Minutes

​Status Bar Integration

​tmux

​Polybar

​i3status

​Waybar

​Terminal Integration

​Shell Prompt (PS1)

​Coding Agent Integration

​VS Code Status Bar

​JetBrains IDEs

​Neovim/Vim Statusline

​Location Override

​Error Handling

​Silent Failure Behavior

​Fallback Display

​Performance Optimization

​Caching Strategy

​Background Updates

​Complete Examples

​Minimal tmux Setup

​Polybar with Tooltip

​Shell Script Widget

​Testing

​Troubleshooting

​Best Practices

Cache Aggressively

Handle Failures

Suppress Errors

Keep It Simple

​See Also

JSON Output

Agent Usage

Overview

Basic Usage

Output Format

Possible Event Labels

Countdown Format

Status Bar Integration

tmux

Polybar

i3status

Waybar

Terminal Integration

Shell Prompt (PS1)

Coding Agent Integration

VS Code Status Bar

JetBrains IDEs

Neovim/Vim Statusline

Location Override

Error Handling

Silent Failure Behavior

Fallback Display

Performance Optimization

Caching Strategy

Background Updates

Complete Examples

Minimal tmux Setup

Polybar with Tooltip

Shell Script Widget

Testing

Troubleshooting

Best Practices

See Also