📖 quran.sh

A fast, offline-first Quran CLI and TUI reader built with Bun and TypeScript

Features

📚 Reading

• Offline-First — All data bundled, works without internet
• Multi-Pane Reader — Arabic (top), Translation + Transliteration (split below)
• 10 Languages — Bengali, English, Spanish, French, Indonesian, Russian, Swedish, Turkish, Urdu, Chinese — press l to cycle
• Arabic Text Shaping — Proper connected Arabic rendering via arabic-reshaper
• Verse Flow Modes — Stacked, inline, or continuous flow — press F to cycle
• Arabic Layout — Configurable alignment (A) and width (W)

🎨 Design

• 12 Dynasty Themes — Mamluk, Ottoman, Safavid, Andalusian, Maghribi, Madinah, Umayyad, Abbasid, Fatimid, Seljuk, Mughal — each with unique ornaments, borders and color palettes inspired by Islamic manuscript illumination
• Light & Dark Mode — Auto-detection + manual toggle
• Themed Progress Bars — Custom ASCII progress indicators in title bars using dynasty-specific ornament characters
• Focus Indicators — Heavy borders + diamond icon on the focused pane

🔖 Study Tools

• Bookmarks — Mark and revisit favorite verses
• Cues — 9 quick-navigation slots (1–9) for instant jumping
• Reflections — Personal notes attached to any verse
• Activity Panel — Toggleable right panel listing all bookmarks, cues, and reflections
• Full-Text Search — Search across all translations with /
• Command Palette — Quick access to all commands with Ctrl+P

📊 Progress Tracking

• Reading Mode — Toggle between browsing (no tracking) and reading (tracks every verse) with m
• Surah Completion — When navigating away from a surah in reading mode, prompted to mark it as complete
• Reading Stats — Sidebar widget showing verses read, unique verses, surahs touched, and surahs completed — filterable by Today, Week, Month, All Time, and Session
• Streak Tracking — Current streak, longest streak, and total reading days via CLI
• Verse Logging — Log individual verses or full surahs as read via CLI

💾 Persistence

• SQLite Database — All bookmarks, cues, reflections, reading logs, and preferences stored locally
• Auto-Restore — Selected surah, verse position, theme, language, layout, sidebar/panel visibility, and reading mode all persist across sessions

Installation

# Run directly (no install)
bunx quran.sh

# Global install
bun install -g quran.sh

# Or with npm
npm install -g quran.sh

Usage

CLI Commands

# Launch interactive TUI
quran

# Read a surah (by number or name)
quran read 1
quran read al-fatihah

# Read a specific verse
quran read 2:255

# Search for verses
quran search "merciful"

# Log reading progress
quran log 1
quran log 2:255

# View reading streak
quran streak

TUI Keyboard Shortcuts

Navigation

| Key | Action | |-----|--------| | Tab | Cycle focus: Sidebar → Arabic → Translation → Transliteration → Panel | | Shift+Tab | Cycle sidebar focus: Surah List ↔ Reading Stats | | ↑/↓ or j/k | Navigate surahs or verses | | Enter | Select surah (in sidebar) | | 1-9 | Jump to cue slot |

Pane Toggles

| Key | Action | |-----|--------| | a | Toggle Arabic pane | | t | Toggle Translation pane | | r | Toggle Transliteration pane | | s | Toggle sidebar | | B | Toggle activity panel (Bookmarks / Cues / Reflections) |

Study

| Key | Action | |-----|--------| | b | Toggle bookmark on current verse | | R | Add/edit reflection | | ! to ( | Set cue 1–9 (Shift+1–9) | | / | Search verses | | m | Toggle Reading/Browsing mode |

Display

| Key | Action | |-----|--------| | T | Cycle dynasty theme | | D | Cycle light/dark mode | | +/- | Increase/decrease verse spacing | | A | Cycle Arabic alignment | | W | Cycle Arabic width | | F | Cycle verse flow mode |

General

| Key | Action | |-----|--------| | Ctrl+P | Open command palette | | ? | Show/hide help dialog | | ESC | Dismiss dialog / Clear search | | q | Quit |

Data Source

• Translations from quran-json
• 114 surahs, 6,236 verses
• 10 languages: Bengali, English, Spanish, French, Indonesian, Russian, Swedish, Turkish, Urdu, Chinese

Development

# Clone
git clone https://github.com/smashah/quran.sh.git
cd quran.sh

# Install dependencies
bun install

# Run TUI
bun run src/index.ts

# Run CLI
bun run src/index.ts read 1

# Run tests
bun test

# Build standalone binary
bun run build
# → outputs ./dist/quran

Recording Demos

Demo recording scripts are in demos/. To record a TUI demo:

# 1. Start a tmux session
tmux new-session -d -s demo -x 120 -y 35

# 2. Start terminalizer inside it
tmux send-keys -t demo 'terminalizer record --config demos/tui-demo.yml demos/tui-full -k' Enter

# 3. Run the keystroke automation (in another terminal)
bash demos/send-keys.sh

# 4. Render to GIF
terminalizer render demos/tui-full

License

MIT © smashah

Credits

• Built with Bun
• UI powered by OpenTUI
• Arabic shaping via arabic-reshaper
• Data from quran-json

Made with ❤️ for the Muslim community