yoinks

Product Introduction

1. Definition: Yoinks is a command-line interface (CLI) tool and terminal application designed for downloading video content from over 1,800 websites, including YouTube, X/Twitter, Instagram, Threads, and TikTok. It is a Node.js-based wrapper for the yt-dlp engine.
2. Core Value Proposition: Yoinks exists to provide a secure, efficient, and ad-free video downloading experience directly from the terminal. It eliminates the need to navigate intrusive ads, pop-ups, and potentially malicious third-party download websites, offering developers and power users a clean, scriptable workflow for video archiving.

Main Features

1. Terminal-Based Interactive Picker: Upon launching with a URL, Yoinks renders a full-screen, centered TUI (Terminal User Interface) built with the Ink library (React for CLIs). Users navigate available video and audio formats (including resolution selection and MP3 extraction) using keyboard shortcuts (↑/↓, j/k, number keys) or direct mouse clicks on interactive elements.
2. Automatic Dependency Management: The tool solves the complex setup of video downloading tools. On first run, it automatically fetches the standalone yt-dlp binary to ~/.yoinks/bin, requiring no Python installation. For FFmpeg operations (like merging streams or audio conversion), it first checks the user's system PATH and falls back to a bundled ffmpeg-static binary if not found.
3. Theme-Aware Terminal UI: The interface respects user preferences by default. It uses an "auto" theme that adopts the terminal's own foreground and background colors. Users can manually cycle themes (auto/light/dark) during a session with Ctrl+T or by clicking the footer control, ensuring readability across different terminal color schemes.

Problems Solved

1. Pain Point: It directly addresses the security risks and user experience friction associated with web-based video downloaders, which are often laden with deceptive ads, fake download buttons, and redirects to malicious sites.
2. Target Audience: Primary user personas include software developers, sysadmins, data scientists, researchers, and technical power users who are comfortable in the terminal and prioritize automation, security, and a clutter-free workflow for media collection and archiving.
3. Use Cases: Essential for creating local archives of tutorial videos for offline viewing, downloading social media clips for fair-use analysis or content review, batch-saving reference materials in a development environment, or quickly grabbing video assets without leaving a coding workflow.

Unique Advantages

1. Differentiation: Unlike web-based services, Yoinks operates locally, enhancing privacy and security. Compared to using yt-dlp directly, it adds a discoverable, intuitive TUI that simplifies format selection without memorizing command-line flags, lowering the barrier to entry while retaining full backend power.
2. Key Innovation: Its seamless, zero-configuration bundling of the critical backend tools (yt-dlp, FFmpeg) into a single Node.js package installable via npm/npx. This "it just works" approach for a complex toolchain, combined with a production-grade React terminal UI, is its standout technical achievement.

Frequently Asked Questions (FAQ)

1. Is Yoinks safe to use compared to online video downloaders? Yes, Yoinks is generally safer as it runs locally on your machine using the reputable yt-dlp engine. It avoids the security risks of interacting with ad-laden, third-party websites that may host malware or phishing attempts.
2. Does Yoinks require Python or FFmpeg to be installed separately? No, a key feature of Yoinks is automatic dependency management. It downloads a standalone yt-dlp binary without Python, and includes a fallback FFmpeg binary, requiring no prior system setup for core functionality.
3. Can I use Yoinks in a script or automate downloads without the interactive menu? The current version focuses on the interactive TUI. However, the project roadmap lists --best and --mp3 flags for a scriptable, non-interactive mode as a planned future feature.
4. Where are videos downloaded to, and can I change the output directory? By default, Yoinks saves downloaded files to the user's ~/Downloads folder. The roadmap includes an -o <dir> flag to specify a custom output directory, which is not yet implemented in the current release.
5. Is it legal to download videos with Yoinks? Yoinks is a tool. Legality depends on your jurisdiction, the website's Terms of Service, and your intended use (e.g., personal archiving vs. redistribution). It is intended for downloading content you have the right to archive, and users must respect copyright and platform rules.