Agent Usage

Use ramadan-cli as an agent skill for automated workflows and AI-powered tools

Overview

Ramadan CLI is built for both humans and agents. It can be installed as a skill package for coding agents and AI tools, providing programmatic access to Ramadan prayer times with multiple output formats.

Installation

Installing as a Skill

Add ramadan-cli to your agent’s skill registry:

npx skills add ahmadawais/ramadan-cli

This installs the CLI as a skill package that agents can invoke to retrieve Sehar and Iftar timings.

Manual Installation

For direct integration:

npm install -g ramadan-cli@latest

Agent-Friendly Features

JSON Output

Structured JSON format for parsing and processing

Status Line Mode

Single-line output perfect for status bars

Non-Interactive Config

Programmatic configuration without prompts

Isolated State

Environment variable for isolated config storage

Isolated Configuration

Always isolate config in automation to avoid polluting user or global state.

Use the RAMADAN_CLI_CONFIG_DIR environment variable to specify an isolated config directory:

# Create isolated config directory
TMP_CFG="/tmp/ramadan-cli-agent"
mkdir -p "$TMP_CFG"

# Run with isolated config
RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli sf
RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli --json

Reset Isolated State

RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli reset

Non-Interactive Configuration

Configure the CLI programmatically without interactive prompts:

1. Set Location and Settings

   Use the config command with flags to set all required parameters:

   ramadan-cli config \
     --city "San Francisco" \
     --country "United States" \
     --latitude 37.7749 \
     --longitude -122.4194 \
     --method 2 \
     --school 0 \
     --timezone "America/Los_Angeles"
   
2. Verify Configuration

   Check the saved configuration:

   ramadan-cli config --show
   
3. Use the Configuration

   All subsequent commands will use the saved settings:

   ramadan-cli --json
   ramadan-cli -s
   

Config Management

Show Config

ramadan-cli config --show

Agent Usage Patterns

Query Without Saved Config

Agents can query specific cities without saving configuration:

# One-off city query
ramadan-cli "Lahore" --json
ramadan-cli sf --status
ramadan-cli "Dubai, UAE" --json

One-off city queries do not overwrite saved default location.

Handling Interactive Prompts

The CLI behavior depends on the output mode:

JSON Mode

Automatically skips interactive setup:

# No prompts, even on first run
ramadan-cli --json

Falls back to IP geolocation if no config exists.

Status Mode

Automatically skips interactive setup:

# No prompts, silent failure
ramadan-cli --status

Returns no output if location cannot be detected.

Standard Mode

Will prompt interactively if:

• Running in a TTY
• No config exists
• No city is specified

Agents should use --json or configure explicitly.

Exit Codes and Error Handling

The CLI uses standard exit codes for automation:

Exit Code	Meaning
0	Success
1	Runtime failure (network/API/validation/data)

Error Handling in Scripts

#!/bin/bash

# Check if ramadan-cli is available
if ! command -v ramadan-cli &> /dev/null; then
    echo "ramadan-cli not found"
    exit 1
fi

# Fetch data with error handling
if OUTPUT=$(ramadan-cli --json 2>&1); then
    echo "Success: $OUTPUT"
else
    echo "Failed to fetch Ramadan timings"
    exit 1
fi

JSON Error Format

When using --json, errors are written to stderr as structured JSON:

{
  "ok": false,
  "error": {
    "code": "LOCATION_DETECTION_FAILED",
    "message": "Could not detect location. Pass a city like `ramadan-cli \"Lahore\"`."
  }
}

Error Codes Reference

Code	Description
INVALID_FIRST_ROZA_DATE	Invalid date format for --first-roza-date
INVALID_FLAG_COMBINATION	Conflicting flags (e.g., --all with --number)
PRAYER_TIMES_FETCH_FAILED	Could not fetch prayer times from API
RAMADAN_CALENDAR_FETCH_FAILED	Could not fetch Ramadan calendar
LOCATION_DETECTION_FAILED	Could not detect or resolve location
ROZA_NOT_FOUND	Specified roza number not found
RAMADAN_CLI_ERROR	General error
UNKNOWN_ERROR	Unexpected error occurred

Example: Agent Integration

Here’s a complete example of integrating ramadan-cli into an agent workflow:

Setup Script

#!/bin/bash
set -e

# Create isolated config directory
CONFIG_DIR="/tmp/ramadan-agent-${RANDOM}"
mkdir -p "$CONFIG_DIR"

# Export for all subsequent commands
export RAMADAN_CLI_CONFIG_DIR="$CONFIG_DIR"

# Configure non-interactively
ramadan-cli config \
  --city "New York" \
  --country "United States" \
  --method 2 \
  --school 0 \
  --timezone "America/New_York"

echo "Configuration complete"

Testing Agent Integration

1. Test Basic Invocation

   ramadan-cli --help
   ramadan-cli --version
   
2. Test JSON Output

   ramadan-cli sf --json | jq '.'
   
3. Test Error Handling

   # Invalid flag combination
   ramadan-cli --all --number 5 2>&1
   
   # JSON error output
   ramadan-cli --all --number 5 --json 2>&1 | jq '.error'
   
4. Test Isolated Config

   TMP_CFG="/tmp/test-config"
   mkdir -p "$TMP_CFG"
   RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli config --city "Toronto" --country "Canada"
   RAMADAN_CLI_CONFIG_DIR="$TMP_CFG" ramadan-cli config --show
   

Best Practices

Use Isolated Config Directories

Always set RAMADAN_CLI_CONFIG_DIR to avoid interfering with user configuration:

export RAMADAN_CLI_CONFIG_DIR="/tmp/my-agent-$(date +%s)"

Prefer JSON Output

Use --json for reliable parsing and to skip interactive prompts:

ramadan-cli --json | jq -r '.rows[0].iftar'

Handle Errors Gracefully

Check exit codes and parse error JSON:

if ! OUTPUT=$(ramadan-cli --json 2>&1); then
    ERROR=$(echo "$OUTPUT" | jq -r '.error.message')
    echo "Error: $ERROR"
fi

Use Status Mode for Display

For status bars and simple displays, use --status:

ramadan-cli --status

See Also

JSON Output

Learn about the JSON output structure

Status Line Mode

Integrate with status bars and displays