itqan-cli

Itqan Quranic Asset Manager

Install and pin Itqan Quranic assets (mushafs, tafsirs, translations, fonts) in your project, the way a package manager does for code.

You declare the assets you use and the versions you accept in itqan-assets.yaml. The CLI resolves them against the Itqan registry, downloads them, and records the exact versions in itqan-assets.lock, so teammates and CI get the same files.

Install

Requires Python 3.11+.

pipx install itqan-cli        # or: uv tool install itqan-cli

This installs the itqan command; itqan-cli is the same command under the package's name.

Homebrew

On macOS (Apple Silicon or Intel) and Linux, without Python:

brew install itqan-community/tap/itqan
brew upgrade itqan    # later, to update

npm

For JavaScript and React Native projects, without Python:

npx itqan-cli init
npx itqan-cli install

Or add it to your project and run itqan install from your package.json scripts:

npm install --save-dev itqan-cli

It runs the standalone binary for your platform (macOS, Linux with glibc, Windows), installed as an optional dependency, so don't install with --omit=optional.

Without Python

Each GitHub Release has a standalone itqan executable for macOS (arm64, x86_64), Linux (x86_64, arm64) and Windows (x86_64), named itqan-<version>-<os>-<arch> (.exe on Windows). Download yours, check it against SHA256SUMS and put it on your PATH as itqan. For example, on an Apple Silicon Mac:

v=0.2.0   # the release you want
curl -fLO "https://github.com/Itqan-community/itqan-cli/releases/download/v$v/itqan-$v-macos-arm64"
curl -fLO "https://github.com/Itqan-community/itqan-cli/releases/download/v$v/SHA256SUMS"
shasum -a 256 --check --ignore-missing SHA256SUMS
chmod +x "itqan-$v-macos-arm64"
sudo mv "itqan-$v-macos-arm64" /usr/local/bin/itqan

The binaries aren't notarized by Apple, so macOS blocks one downloaded with a browser. Clear the quarantine flag to allow it: xattr -d com.apple.quarantine /usr/local/bin/itqan. (curl doesn't set the flag.) On Linux, use sha256sum --check --ignore-missing SHA256SUMS.

Quick start

itqan init        # writes itqan-assets.yaml with a few real assets as examples
itqan browse      # search the catalog and add more assets to it
itqan install     # downloads them and writes itqan-assets.lock

Commit both itqan-assets.yaml and itqan-assets.lock. The downloaded files are reproducible from the lockfile, so add the assets folder to .gitignore if you like.

The manifest

schema_version: 1

# Folder the assets are downloaded into, relative to this file (default: assets).
assets_dir: "public/quran"

assets:
  # Source language of the asset.
  tafsir-jalalayn:
    version: "^2.0.0"     # any 2.x from 2.0.0 on

  # The same asset in English: its own entry, pointing at the asset.
  tafsir-jalalayn-en:
    asset: tafsir-jalalayn
    language: en
    version: "~1.3"       # any 1.3.x

Each language of an asset has its own version history, so each gets its own entry, constraint, lock entry and folder (public/quran/tafsir-jalalayn-en/). The full format is specified in ASSET_MANIFEST.md.

Commands

Configuration

itqan login saves keys in ~/.config/itqan/credentials (%APPDATA%\itqan on Windows; set ITQAN_CONFIG_DIR to move it). --api-key and ITQAN_API_KEY, for CI, take precedence over it.

Assets that need access approval

Some publishers approve each developer before their assets can be downloaded. itqan browse lists these too, marked request access, access pending or access rejected, with a link to the asset's page on cms.itqan.dev where you request access. They can't be added until your request is approved; then run itqan login with your API key and they show as granted. itqan install says which assets in your manifest still need access, and where to ask.

Development

uv sync
uv run pytest
uv build
uv run --group binary pyinstaller --onefile --name itqan --copy-metadata itqan-cli --specpath build src/itqan_cli/__main__.py  # dist/itqan

Releases are published from version tags; see RELEASING.md.