Metadata-Version: 2.4
Name: pinak-cli
Version: 1.1.1
Summary: A powerful, aesthetic command-line media downloader using yt-dlp
Author: Pinak Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/pinak-project/pinak-cli
Project-URL: Repository, https://github.com/pinak-project/pinak-cli
Keywords: yt-dlp,downloader,cli,video,media,instagram
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp>=2025.1.1
Requires-Dist: static-ffmpeg>=2.5
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: win11toast; sys_platform == "win32"
Requires-Dist: questionary
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: platformdirs
Requires-Dist: typer
Requires-Dist: Pillow>=10.0.0
Requires-Dist: mutagen>=1.47
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: cyclonedx-bom>=7.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Requires-Dist: pytest-mock>=3.12; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Provides-Extra: ffmpeg
Requires-Dist: static-ffmpeg>=2.5; extra == "ffmpeg"
Dynamic: license-file

# 🔱 PINAK CLI — Media Content Downloader

PINAK CLI is a powerful, highly aesthetic command-line media downloader wrapper around `yt-dlp` and `ffmpeg`. It features a rich, interactive REPL shell with auto-completions, suggestions, customized banners, diagnostic tools, and automatic download tracking.

---

## 🚀 Key Features

*   **Interactive REPL Shell**: Features a terminal command prompt with auto-completions, command suggestions, and command history.
*   **Aesthetic UI**: Powered by `rich` and `prompt-toolkit` with vibrant color themes, tables, custom progress bars, and desktop toast notifications.
*   **Media Formats**: Download as best-quality video, select resolutions (360p, 720p, 1080p, etc.), or convert directly to high-quality MP3 audio.
*   **Local-First & Private**: All data, settings, and download histories remain strictly local on your machine with zero remote tracking.
*   **Self-Diagnostics**: High-detail environmental doctor checks (`/doctor`) to verify internet, dependencies, rate limits, and configuration.
*   **Local SQLite History**: Keeps record of your download URLs, sizes, durations, and output paths in a local SQLite database (`history.db`).

---

## 📦 Directory Structure

```text
cli/
├── pinak/                      # Core Package Folder
│   ├── __init__.py
│   ├── __main__.py             # Entry point (python -m pinak)
│   ├── cli.py                  # REPL Interactive Shell & Typer CLI handler
│   ├── commands/               # Modular REPL & info subcommands
│   ├── downloader.py           # yt-dlp & FFmpeg downloader logic
│   ├── config.py               # Application configurations (Pydantic-Settings)
│   ├── history.py              # SQLite storage & local tracking
│   ├── doctor.py               # Dependencies & connection diagnostics
│   ├── ffmpeg_setup.py         # Static FFmpeg installer utility
│   ├── notify.py               # Desktop notifications & terminal banners
│   ├── updater.py              # Update checker
│   └── utils.py                # Formatting & utility helpers
├── tests/                      # Automated test suite (pytest)
├── pyproject.toml              # Pyproject packaging config
├── requirements-lock.txt       # Locked dependencies for reproducible installs
├── Dockerfile                  # Container image (ffmpeg included)
├── .dockerignore               # Docker build ignore patterns
└── LICENSE                     # MIT license
```

> **Note:** FFmpeg is *not* bundled with the PyPI package. See
> [FFmpeg setup](#-ffmpeg-setup) below — one command installs it.

---

## 🛠️ Installation & Setup

### Requirements
*   Python 3.10 or higher.
*   FFmpeg (see [FFmpeg setup](#-ffmpeg-setup) — one command).

### Step 1: Install from PyPI

```bash
pip install pinak-cli
# recommended (isolated, always on PATH):
pipx install pinak-cli
```

This registers the global `pinak` command. From source (developers):

```bash
cd cli
pip install -e ".[dev]"
```

### Step 2: Test Command

```bash
pinak --doctor
pinak
```

> **`pinak` not found after install?** Your Python Scripts folder isn't on
> PATH. Either add it, use `pipx install pinak-cli`, or run
> `python -m pinak` instead — it works identically. `pinak --doctor`
> includes a "CLI on PATH" check that tells you exactly what to do.

---

## 🎞️ FFmpeg setup

FFmpeg merges formats and extracts MP3s. Pick one option:

```bash
pinak --install-ffmpeg        # single-command mode: downloads a static build
/ffmpeg                        # same thing, inside the interactive REPL
pip install "pinak-cli[ffmpeg]"  # manual equivalent (static-ffmpeg extra)
```

Or install FFmpeg system-wide ([ffmpeg.org/download](https://ffmpeg.org/download.html))
and make sure it is on PATH. Docker users already have it (`cli/Dockerfile`).

---

## 🔄 Keeping everything fresh

Sites change often; an outdated `yt-dlp` is the #1 cause of sudden failures.
Pinak checks PyPI in the background (max once per day) and notifies you —
about new `yt-dlp` **and** new Pinak releases. Inside the REPL, update both
any time with:

```
/update
```

This runs `pip install --upgrade yt-dlp` and `pip install --upgrade
pinak-cli`, tells you exactly what changed (`Updated … 1.0.0 → 1.1.0` vs
`already the latest`), and — if Pinak itself was upgraded — asks you to
restart the CLI (`/exit`, then run `pinak` again) so the new version loads.

---

## 💻 CLI Commands

When running the interactive REPL shell (`pinak`), the following commands are available:

| Command | Description |
| :--- | :--- |
| `/help` | Display the list of all available commands and shortcuts |
| `/doctor` | Run comprehensive environment and connectivity checks |
| `/audio <url>` | Download the media from the URL as an MP3 audio track |
| `/video <url>` | Download video from a URL |
| `/instagram <url>` | Download Instagram post, reel, or IGTV with metadata |
| `/batch <file>` | Download multiple URLs from a text file |
| `/history` | View a list of recent downloads from your history database |
| `/config` | Print out the current config settings and environment |
| `/setout <dir>` | Change the output downloads directory |
| `/open` | Open the downloads directory in File Explorer |
| `/platform [q]` | List supported platforms or search filter them |
| `/update` | Update yt-dlp and Pinak CLI to the latest versions |
| `/ffmpeg` | Download a static FFmpeg build automatically |
| `/exit` | Terminate the interactive REPL shell |

---

## ⚙️ Configuration File

Pinak CLI saves user-specific configuration (like download directory, quality, retry counts) in a standard configuration folder (via `platformdirs`).

- **Windows**: `%LOCALAPPDATA%\pinak\pinak-cli\config.json`
- **macOS**: `~/Library/Application Support/pinak-cli/config.json`
- **Linux**: `~/.config/pinak-cli/config.json`
- **SQLite history**: alongside it (`history.db`)

Run `pinak --config-path` anywhere to print your exact path, or `/config`
inside the REPL (the path is shown above the table). Change the output
folder with `/setout <absolute_path>`.

---

## 🔒 Privacy & Local-First

Pinak CLI is strictly local-first and privacy-focused. All configuration, download history, and media files remain on your local machine. No external tracking or telemetry is performed.

---

## ⚖️ Educational Purpose & Legal Disclaimer

Pinak CLI is developed as an **educational project, technical study of CLI architecture, and personal-archiving tool** wrapper around `yt-dlp` and `ffmpeg`. You are solely responsible for how you use it:

- **Personal Archival Only:** Only download content you own, that is freely licensed (e.g., Creative Commons), or that you have explicit permission to save.
- **Terms of Service:** Automated downloading may violate the Terms of Service of platforms such as YouTube, Instagram, or TikTok; your account or IP could be restricted by those platforms. Use at your own risk.
- **Be Excellent to Creators:** Do not use this tool to pirate, redistribute, or monetize copyrighted material without authorization. Always support and respect creators.
- **No DRM Circumvention:** Pinak CLI does not bypass or defeat Digital Rights Management (DRM) or access restrictions.
- **Limitation of Liability:** The authors provide this software "as is" under the [MIT License](LICENSE) and accept no liability for misuse.
