Quran Reader CLI

A command-line tool to read Quran surahs, verses, and search the Quran using the quran.com API.

Installation

npm install -g quran-reader-cli

Or run directly with npx:

npx quran-reader-cli

Usage

Interactive Mode

Run without arguments to enter interactive mode:

quran

Direct Commands

# Read entire surah (Arabic text)
quran 1

# Read specific verse
quran 2:255

# Read verse range
quran 36:1-10

# Search the Quran (returns Arabic + English translation)
quran search mercy

# List all surahs
quran list

Commands

| Command | Description | |---------|-------------| | <surah> | Read entire surah (e.g., 1) | | <surah>:<verse> | Read specific verse (e.g., 2:255) | | <surah>:<start>-<end> | Read verse range (e.g., 1:1-7) | | search <query> | Search the Quran with English translation | | list | List all 114 surahs | | help | Show help message | | q / quit | Exit interactive mode |

Features

• Read Surahs: View any surah by number (1-114)
• Read Verses: Access specific verses or verse ranges
• Search: Search across the entire Quran with English translations
• Arabic Text: Displays Uthmani script
• Offline Cache: Caches surah list for faster subsequent access
• Interactive Mode: REPL-style interface for continuous reading

Programmatic Usage

import { QuranReader } from 'quran-reader-cli';

const reader = new QuranReader();

// Get surah info
const surah = await reader.getSurah(1);
console.log(surah.name_simple); // Al-Fatihah

// Get verses
const verses = await reader.getVerses(1);
for (const verse of verses) {
  console.log(verse.text_uthmani);
}

// Get specific verse
const ayatulKursi = await reader.getVerse(2, 255);

// Search the Quran
const results = await reader.search('mercy');
for (const result of results) {
  console.log(`${result.verseKey}: ${result.arabic}`);
  console.log(result.translation);
}

API

QuranReader

getSurah(surahNumber: number): Promise<Chapter | null>

Fetch surah metadata.

getAllSurahs(): Promise<Chapter[]>

Fetch all 114 surahs (cached after first call).

getVerses(surahNumber, options?): Promise<Verse[]>

Fetch verses from a surah.

Options:

• startVerse: Starting verse number (default: 1)
• endVerse: Ending verse number (default: all)
• translationId: Translation resource ID (default: 131)

getVerse(surahNumber, verseNumber, translationId?): Promise<Verse | null>

Fetch a single verse.

search(query, options?): Promise<SearchResult[]>

Search the Quran. Returns results with Arabic text and English translation.

Options:

• size: Max results (default: 20)
• translationId: Translation resource ID (default: 131)

Data Source

This tool uses the Quran.com API v4 for Quran text and translations.

License

MIT