GwaniCLI

A command-line interface for accessing Quranic verses and translations with elegant formatting and caching capabilities.

Features

• 🔄 Random verses: Get random Quranic verses with translations
• 📖 Surah browsing: Access specific surahs and ayahs
• 🌍 Multiple translations: Support for various translation options
• 💾 Smart caching: Offline access with configurable TTL
• 🎨 Beautiful formatting: Colored console output with Arabic text support
• ⚙️ Configurable: User-friendly configuration management
• 📱 JSON output: Machine-readable output option

Installation

From PyPI

pip install gwanicli

From Source

git clone https://github.com/bhantsi/gwani-cli.git
cd gwani-cli
pip install -e .

Quick Start

Get a random verse

gwani random

Get a specific surah

gwani surah 1  # Al-Fatiha
gwani surah "Al-Baqarah" --ayah 255  # Ayat al-Kursi

Configure translation

gwani config set translation en.sahih
gwani config get translation

JSON output

gwani random --json

Commands

gwani random

Get a random Quranic verse with translation.

Options:

• --translation, -t TEXT: Specify translation (e.g., en.pickthall)
• --no-cache: Skip cache and fetch fresh data
• --json: Output in JSON format

Examples:

gwani random
gwani random --translation en.sahih
gwani random --json --no-cache

Arabic Text Display

GwaniCLI provides intelligent Arabic text rendering that automatically adapts to your terminal's capabilities.

Display Modes

Use the global --arabic-mode option to control how Arabic text is displayed:

# Automatic detection (default)
gwani random

# Unicode Arabic text only
gwani --arabic-mode unicode random

# Transliterated text only  
gwani --arabic-mode transliteration random

# Both Arabic and transliteration
gwani --arabic-mode both random

Font Recommendations

Check your terminal's Arabic support and get font recommendations:

gwani fonts

For optimal Arabic display, consider installing these fonts:

Ubuntu/Debian:

sudo apt install fonts-noto fonts-amiri fonts-scheherazade-new

macOS (with Homebrew):

brew install --cask font-noto-sans-arabic font-amiri font-scheherazade-new

Recommended fonts:

• Noto Sans Arabic (comprehensive Unicode support)
• Amiri (traditional Arabic calligraphy)
• Cairo (modern, clean Arabic font)
• Scheherazade New (academic/traditional style)

Terminal Compatibility

GwaniCLI works with any terminal:

• Modern terminals (xterm, GNOME Terminal, iTerm2, etc.): Full Unicode Arabic support
• Basic terminals: Automatic fallback to transliteration
• Windows: Enhanced UTF-8 support with automatic optimizations

gwani surah <identifier>

Get verses from a specific surah by number or name.

Arguments:

• identifier: Surah number (1-114) or name (e.g., "Al-Fatiha")

Options:

• --ayah, -a INT: Specific ayah number
• --translation, -t TEXT: Specify translation
• --no-cache: Skip cache and fetch fresh data
• --json: Output in JSON format

Examples:

gwani surah 1                    # Entire Al-Fatiha
gwani surah 2 --ayah 255        # Ayat al-Kursi
gwani surah "Al-Fatiha" --json  # JSON format

gwani fonts

Check Arabic text display capabilities and get font recommendations.

Examples:

gwani fonts  # Check terminal capabilities and show font recommendations

This command will:

• Test your terminal's Arabic text support
• Show terminal and encoding information
• Display sample Arabic text in different modes
• Provide font installation instructions for your platform

gwani config

Manage configuration settings.

Subcommands:

• set <key> <value>: Set a configuration value
• get <key>: Get a configuration value

Supported Keys:

• translation: Default translation (e.g., en.pickthall)
• cache_ttl: Cache time-to-live in seconds

Examples:

gwani config set translation en.sahih
gwani config set cache_ttl 3600
gwani config get translation

gwani version

Show version information.

Configuration

GwaniCLI stores configuration in ~/.config/gwanicli/config.toml.

Default configuration:

translation = "en.pickthall"
cache_ttl = 86400

Caching

The application caches API responses to improve performance and enable offline access:

• Location: ~/.cache/gwanicli/cache.db
• Storage: SQLite database
• TTL: Configurable expiration time
• Management: Automatic cleanup of expired entries

Translations

Common translation identifiers:

• en.pickthall: Pickthall English translation
• en.sahih: Sahih International
• en.yusufali: Abdullah Yusuf Ali
• ar.alafasy: Arabic (Mishary Alafasy)

Development

Setup Development Environment

git clone https://github.com/bhantsi/gwani-cli.git
cd gwani-cli
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Run Tests

pytest

Code Formatting

black qwanicli/
flake8 qwanicli/
mypy qwanicli/

Project Structure

qwanicli/
├── __init__.py      # Package initialization
├── cli.py           # Main CLI entry point with Click commands
├── api_client.py    # HTTP client for Quran API
├── config.py        # Configuration management
├── cache.py         # SQLite-based caching layer
├── formatter.py     # Output formatting (console & JSON)
└── utils.py         # Common utilities and error handling

API

GwaniCLI uses the Al-Quran Cloud API to fetch Quranic content.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Al-Quran Cloud API for providing the Quranic data
• Click for the excellent CLI framework
• The open-source community for various Python packages used

Support

If you encounter any issues or have questions:

1. Check the Issues
2. Create a new issue

---

Note: This tool is for educational and personal use. Please respect the sacred nature of the Quranic content.