Metadata-Version: 2.5
Name: itqan-cli
Version: 0.1.3
Summary: Itqan Quranic Asset Manager: install and pin Itqan Quranic assets in your project.
Project-URL: Homepage, https://github.com/Itqan-community/itqan-cli
Project-URL: Repository, https://github.com/Itqan-community/itqan-cli
Project-URL: Issues, https://github.com/Itqan-community/itqan-cli/issues
Project-URL: Manifest format, https://github.com/Itqan-community/cms-backend/blob/main/docs/ASSET_MANIFEST.md
Author: Itqan
Author-email: Hassaan Alansary <hassaanalansary@yahoo.com>
License-Expression: MIT
License-File: LICENSE
Keywords: assets,cli,itqan,mushaf,package-manager,quran,quranic,tafsir
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Religion
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.1
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# itqan-cli

**Itqan Quranic Asset Manager**

Install and pin [Itqan](https://cms.itqan.dev) 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+.

```bash
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:

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

### npm

For JavaScript and React Native projects, without Python:

```bash
npx itqan-cli init
npx itqan-cli install
```

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

```bash
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](https://github.com/Itqan-community/itqan-cli/releases) 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:

```bash
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

```bash
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

```yaml
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](https://github.com/Itqan-community/cms-backend/blob/main/docs/ASSET_MANIFEST.md).

## Commands

| Command | What it does |
|---|---|
| `itqan init` | Create `itqan-assets.yaml` from the registry's catalog (commented examples when offline). `--assets-dir`, `--force`. |
| `itqan browse [QUERY]` | Search the registry's catalog and pick assets to add to `itqan-assets.yaml` (created if missing), then optionally install them. Type in the picker to filter further. `--category`, `--no-interactive` (print a table; the default outside a terminal), `--json`. |
| `itqan login` | Save your API key (create one at [cms.itqan.dev/account/api-keys](https://cms.itqan.dev/account/api-keys)). The key is checked first, then saved for that registry, readable only by you. `--api-key` to pass it without the prompt. |
| `itqan logout` | Remove the saved key. |
| `itqan install` | Resolve, download and lock. Uses the lockfile's exact versions when it is up to date; `--force` re-resolves. |
| `itqan sync` | Same as `install`. |
| `itqan --version` | Print the CLI version. |

## Configuration

| Option | Environment variable | Default |
|---|---|---|
| `--registry-url` | `ITQAN_REGISTRY_URL` | `https://api.cms.itqan.dev` |
| `--api-key` | `ITQAN_API_KEY` | the key saved by `itqan login` for the registry, if any |

`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

```bash
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](RELEASING.md).
