yoink-cli 0.1.0

A friendly, scriptable CLI for downloading media and extracting information from video URLs.

Yoink

Yoink is a friendly, scriptable CLI for downloading media and extracting information from video URLs. It uses 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.

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:

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

Interactive mode

Run Yoink without any arguments:

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:

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:

◆ 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:

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

Limit the resolution and choose an output directory:

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

Download audio:

yoink audio URL
yoink audio URL --codec flac

Download the video stream without audio:

yoink video-only URL --quality 720

Print metadata, or save it as JSON:

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

Download or convert the thumbnail:

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

Inspect the available streams:

yoink formats URL

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

yoink audio PLAYLIST_URL --playlist

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

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.