Metadata-Version: 2.4
Name: yoink-cli
Version: 0.1.0
Summary: A friendly, scriptable CLI for downloading media and extracting information from video URLs.
Project-URL: Homepage, https://github.com/saral-gupta7/yoink
Project-URL: Repository, https://github.com/saral-gupta7/yoink
Project-URL: Issues, https://github.com/saral-gupta7/yoink/issues
Author: Saral Gupta
License-Expression: MIT
License-File: LICENSE
Keywords: audio,cli,downloader,video,youtube,yt-dlp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: questionary<3,>=2.1.1
Requires-Dist: typer<1,>=0.15.1
Requires-Dist: yt-dlp>=2026.1.29
Provides-Extra: dev
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# Yoink

Yoink is a friendly, scriptable CLI for downloading media and extracting
information from video URLs. It uses
[yt-dlp](https://github.com/yt-dlp/yt-dlp) under the hood, so it works with
YouTube and the many other sites supported by yt-dlp.

Only download media you are authorized to access. You are responsible for
following copyright law and each site's terms.

## Install

Python 3.10 or newer is required. `ffmpeg` is also recommended and is required
for audio conversion, thumbnail conversion, and some video stream merges.

```bash
git clone <repository-url>
cd yoink
uv tool install .
yoink doctor
```

`uv tool install .` installs Yoink into an isolated, user-wide environment and
places the `yoink` executable on your `PATH`. It can then be run from any
directory without activating this project's virtual environment. The
repository's `PUBLISHING.md` explains the complete local-install and PyPI
release process.

For development:

```bash
python -m pip install -e ".[dev]"
pytest
ruff check .
```

## Interactive mode

Run Yoink without any arguments:

```bash
yoink
```

Yoink will ask for the video URL, show a keyboard-selectable operation menu,
and prompt only for the settings needed by the selected operation. Use the
arrow keys (or `j`/`k`) to move and Enter to select:

```text
Paste a video URL: https://www.youtube.com/watch?v=VIDEO_ID

◆ Choose an operation (↑/↓ move • enter select)
❯ ▸  Video + audio
  ♫  Audio only
  ▯  Video only
  ◆  Metadata
  ▣  Thumbnail
  ≡  Available formats
```

You can also start the guided flow explicitly with `yoink interactive`.
For download operations, Yoink offers two destinations:

```text
◆ Save files to (↑/↓ move • enter select)
❯ Current directory  ./
  System Downloads  ~/Downloads
```

The current directory is selected by default, so pressing Enter uses it. The
second option resolves to the current user's system Downloads directory.

During downloads, Yoink shows a live progress bar with transferred size,
transfer speed, and estimated time remaining.

## Direct commands

The command-based interface remains available for scripts and automation.

Download the best video with audio:

```bash
yoink video "https://www.youtube.com/watch?v=VIDEO_ID"
```

Limit the resolution and choose an output directory:

```bash
yoink video URL --quality 1080 --output ./downloads
```

Download audio:

```bash
yoink audio URL
yoink audio URL --codec flac
```

Download the video stream without audio:

```bash
yoink video-only URL --quality 720
```

Print metadata, or save it as JSON:

```bash
yoink metadata URL
yoink metadata URL --save info.json
```

Download or convert the thumbnail:

```bash
yoink thumbnail URL
yoink thumbnail URL --format png --output ./artwork
```

Inspect the available streams:

```bash
yoink formats URL
```

Playlist downloads are deliberately disabled by default. Enable them explicitly:

```bash
yoink audio PLAYLIST_URL --playlist
```

For videos requiring an authenticated session, import cookies from a browser:

```bash
yoink video URL --cookies-from-browser chrome
```

Run `yoink COMMAND --help` for every option.

## Architecture

The CLI layer in `src/yoink/cli.py` handles input and presentation. The
`MediaClient` in `src/yoink/core.py` owns yt-dlp configuration and media
operations. New features should normally become a method on `MediaClient` and a
small CLI command that calls it. This keeps the library usable outside the
terminal and makes commands straightforward to test.
