# GwaniCLI
![CI](https://github.com/bhantsi/gwani-cli/workflows/CI%2FCD%20Pipeline/badge.svg)
![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)


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 (when published)
```bash
pip install gwanicli
```

### From Source
```bash
git clone https://github.com/bhantsi/gwani-cli.git
cd gwani-cli
pip install -e .
```

## Quick Start

### Get a random verse
```bash
gwani random
```

### Get a specific surah
```bash
gwani surah 1  # Al-Fatiha
gwani surah "Al-Baqarah" --ayah 255  # Ayat al-Kursi
```

### Configure translation
```bash
gwani config set translation en.sahih
gwani config get translation
```

### JSON output
```bash
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:**
```bash
gwani random
gwani random --translation en.sahih
gwani random --json --no-cache
```

### `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:**
```bash
gwani surah 1                    # Entire Al-Fatiha
gwani surah 2 --ayah 255        # Ayat al-Kursi
gwani surah "Al-Fatiha" --json  # JSON format
```

### `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:**
```bash
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:**
```toml
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
```bash
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
```bash
pytest
```

### Code Formatting
```bash
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](https://alquran.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](LICENSE) file for details.

## Acknowledgments

- [Al-Quran Cloud API](https://alquran.cloud/) for providing the Quranic data
- [Click](https://click.palletsprojects.com/) 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 [FAQ](https://github.com/yourusername/gwani-cli/wiki/FAQ)
2. Search [existing issues](https://github.com/yourusername/gwani-cli/issues)
3. Create a [new issue](https://github.com/yourusername/gwani-cli/issues/new)

---

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