yoinks: A yt-dlp terminal tool for downloading videos from 1,800+ sites
A yt-dlp terminal interface for video archiving across 1,800+ sites, without popups or fake download buttons.
GitHub pablostanley/yoinks Updated 2026-10-02 Branch main Stars 2.9K Forks 276
TypeScript Terminal tool yt-dlp Node 18+ Ink Video downloading

🧭 Decision Guide

Try it if you

  • 你使用Node 18+,想从YouTube、X/Twitter、Instagram或TikTok下载视频。
    README的Install章节要求Node 18+;正文列出YouTube、X/Twitter、Instagram、Threads、TikTok及1,800+网站。
  • 你希望用npx直接运行,并通过Ink界面选择分辨率或audio-only mp3。
    Install章节提供npx yoinks;Usage章节说明可选择resolution或audio-only mp3,How it works章节说明UI使用Ink。
  • 你需要yt-dlp能力但不想单独安装Python。
    How it works章节说明首次运行下载standalone yt-dlp binary到~/.yoinks/bin,并注明no Python required。

Skip it if you

  • 你需要脚本模式中的--best或--mp3,或需要-o指定输出目录。
    Roadmap将--best、--mp3和-o列为未完成项。
  • 你需要Playlist、thread-with-multiple-videos或剪贴板自动检测。
    Roadmap将Playlist / thread-with-multiple-videos和Clipboard detection列为未完成项。
  • 你的下载用途可能违反平台条款,或你需要项目明确提供商业合规保证。
    A note on fair use章节明确提醒下载内容可能违反平台terms of service,并要求只下载有权保留的内容。
  • 你偏好有正式版本和多人维护信号的依赖工具。
    项目元数据显示贡献者1人、版本发布0个、最新版本No releases。

Requirements

  • Node 18+
  • README说明Everything else (yt-dlp, ffmpeg) is fetched or bundled automatically
  • 高分辨率流合并和mp3提取需要ffmpeg;README说明其从PATH查找,并以ffmpeg-static作为bundled fallback
  • 默认输出目录为~/Downloads

First step (verbatim from README)

npx yoinks

Watch out

  • 首次运行会把standalone yt-dlp binary下载到~/.yoinks/bin。
    README的How it works章节。
  • ffmpeg不在PATH时会依赖ffmpeg-static,且它负责高分辨率合并和mp3提取。
    README的How it works章节。
  • yoinks会接管终端全屏,并在退出时恢复scrollback。
    README的Usage章节。
  • Roadmap中的yt-dlp自更新(yt-dlp -U)尚未实现。
    README的Roadmap章节。

Alternatives

  • yt-dlp:需要直接使用yt-dlp命令行参数、绕过yoinks的交互式格式选择,或使用其自身更新机制时更合适。
    How it works;通用领域知识

Not stated in the README

  • README没有说明支持的操作系统范围。
  • README没有说明各平台是否需要登录、Cookie或如何处理受限内容。
  • README没有给出支持的具体格式列表、编码器选择或文件命名规则。
  • README没有说明下载失败、限速、网络中断和重试行为。
  • README没有说明1,800+网站支持对应的yt-dlp版本或兼容性范围。
  • README没有说明npm包的具体版本号,也没有正式GitHub Release。

💡 Deep Analysis

6
No I maintain a batch media-processing script and want to skip the interactive picker with `--best` or `--mp3`, while using `-o` to choose the output directory. Can the current yoinks version be integrated directly?
For: A developer maintaining a scripted media pipeline who depends on `--best`, `--mp3`, or `-o` flags for automated downloads

No, not for the current automation use case, because the README lists these scripting flags as unfinished roadmap items.

  • The roadmap still leaves --best / --mp3 flags to skip the picker (scriptable mode) unchecked.
  • Choosing an output directory with -o is also unfinished; the current Usage section says files are saved to ~/Downloads.
  • The current tool enters a full-screen interactive UI and requires format selection, which does not match a non-interactive batch pipeline.
  • The README says the underlying engine is yt-dlp, so calling yt-dlp directly is closer to an existing parameterized script.

This does not mean yoinks could never support automation. It means the currently documented interface does not promise a stable script mode, output-directory flag, or batch-task API. Playlist and multi-video thread support are also still roadmap items.

  • README “Roadmap”: `--best` / `--mp3` flags to skip the picker remain unchecked
  • README “Roadmap”: `-o` to choose the output folder remains unchecked
  • README “Usage”: formats are selected through the interactive picker; files go to `~/Downloads`
  • README “Roadmap”: playlist and thread-with-multiple-videos support is unfinished
Not stated in the README:The README does not say whether the current version has undocumented scripting flags.;The README does not specify batch tasks, concurrent downloads, exit codes, or machine-readable output.
Yes I do not want to memorize complex yt-dlp format flags, but I can use a terminal. I want to choose resolutions with arrows, j/k, number keys, or a mouse, and switch between dark and light terminal themes. Is yoinks a better fit?
For: A personal archivist accustomed to traditional command-line flags who wants to choose formats in the terminal with arrows, j/k, number keys, or a mouse

Yes, because the README turns format selection and terminal interaction into a visual workflow, reducing the need to memorize yt-dlp flags.

  • The Usage section supports arrows, j/k, number keys, and mouse selection; Esc goes back and Ctrl-C quits.
  • Ink provides a full-screen, centered interface and restores the terminal scrollback on exit.
  • Themes include auto, light, and dark; the auto theme uses the terminal’s own foreground and background colors.
  • Users can run yoinks <url> to enter the picker directly or launch without an argument and enter a URL afterward.

The user still needs to understand terminal interaction and the difference between video formats and MP3. If the requirement is headless scripted downloading, the roadmap’s automation flags are not implemented yet.

  • README “Usage”: arrows, j/k, number keys, mouse, Esc, and `^c`
  • README “Usage”: “full-screen, centered — and restores your scrollback on exit”
  • README “Usage”: themes include `auto`, `light`, and `dark`
  • README “How it works”: “The UI is Ink — React for the terminal”
yoinks https://youtu.be/dQw4w9WgXcQ
Not stated in the README:The README does not list compatibility across terminal emulators, remote sessions, or mouse protocols.;The README does not say whether it falls back to plain text mode without a full TTY.
Yes I mainly archive videos I have the right to keep from YouTube, X/Twitter, Instagram, Threads, and TikTok. I want to finish downloads in the terminal without popups, fake buttons, or suspicious redirects. Is yoinks suitable for me?
For: A terminal user who archives personal content from YouTube, X/Twitter, Instagram, Threads, and TikTok while avoiding web ads and fake download buttons

Yes, because yoinks is specifically designed to turn multi-site downloading into a terminal-based paste, select, and finish workflow.

  • The README lists YouTube, X/Twitter, Instagram, Threads, TikTok, and “1,800+ other sites.”
  • Running yoinks <url> opens the format picker directly, while launching it without an argument prompts for a URL.
  • Files are saved to ~/Downloads by default, and the completed file path is printed in the terminal.
  • The README explicitly promises “No popups, no fake download buttons, no sketchy redirects.”

However, it still depends on yt-dlp and the target platform. Authentication, regional restrictions, private content, and platform changes are not independently solved by yoinks. Platform terms and content rights also remain applicable.

  • README “yoinks”: YouTube, X/Twitter, Instagram, Threads, TikTok, and 1,800+ other sites
  • README “Usage”: `yoinks https://youtu.be/...`; files are saved to `~/Downloads`
  • README “yoinks”: “No popups, no fake download buttons, no sketchy redirects”
  • Project insight “usage_limitations”: it is fundamentally an interactive wrapper around yt-dlp
npx yoinks
Not stated in the README:The README does not specify how login, age restrictions, regional restrictions, or private content are handled.;The README does not define the current support level for playlists or threads containing multiple videos.
No I run tools on a Node.js 18+ server or container and need downloads written to a specified workspace rather than `~/Downloads`. I also want to avoid automatically placing binaries under the user home directory. Is yoinks suitable?
For: An operations developer running Node.js 18+ on a server, container, or shared machine who needs strict output-directory control and does not want writes under a home directory

No, not for a strictly isolated server or container environment, because the README only documents a fixed ~/Downloads output location and places the automatically acquired yt-dlp under the user home directory.

  • The Usage section explicitly says files are saved to ~/Downloads, while custom output with -o is still on the roadmap.
  • The How it works section says the standalone yt-dlp binary is downloaded to ~/.yoinks/bin on first run.
  • The tool takes over the terminal through Ink; a server or container without a complete TTY may not provide a suitable interactive environment.
  • Although Node 18+ is required, the README gives no deployment instructions for containers, users without home directories, or non-TTY mode.

For server-side batch processing, controlled paths, and non-interactive execution, the documented capabilities are insufficient. The project is oriented toward personal terminal use.

  • README “Usage”: “Files are saved to `~/Downloads`”
  • README “Roadmap”: `-o` to choose the output folder is unfinished
  • README “How it works”: yt-dlp is downloaded to `~/.yoinks/bin`
  • Project insight “usage_limitations”: it is not flexible for servers, containers, shared machines, or strict directory isolation
Not stated in the README:The README does not specify support for no-TTY environments, read-only HOME directories, container-user permissions, or proxies.;The README does not say whether environment variables can override `~/Downloads` or `~/.yoinks/bin`.
It depends I use Node.js 18+ and need to extract MP3 files or merge high-resolution video streams from supported sites, but I do not want to install Python or manually configure yt-dlp and ffmpeg. Is yoinks suitable?
For: A Node.js 18+ user who needs MP3 extraction and high-resolution video selection but does not want to manually configure Python, yt-dlp, and ffmpeg

It depends: it is a good fit when dependency acquisition works, but MP3 extraction and high-resolution merging still depend on ffmpeg being usable.

  • The README requires Node 18+ and says yt-dlp and ffmpeg are fetched or bundled automatically, so users do not have to prepare Python manually.
  • On the first run, yt-dlp is downloaded to ~/.yoinks/bin; an existing system yt-dlp is preferred.
  • ffmpeg is first discovered through PATH, with ffmpeg-static as a fallback; it is used for high-resolution stream merging and MP3 extraction.
  • The format picker supports selecting a resolution or audio-only MP3.

If networking, permissions, or the fallback binary fail, conversion and merging may fail. The README does not provide an ffmpeg compatibility matrix or specify fallback-package coverage for every platform.

  • README “Install”: “Requires Node 18+. Everything else (yt-dlp, ffmpeg) is fetched or bundled automatically”
  • README “How it works”: yt-dlp is downloaded to `~/.yoinks/bin`; “no Python required”
  • README “How it works”: ffmpeg is needed for merging high-res streams and MP3 extraction
  • README “Usage”: pick a resolution or audio-only MP3
npx yoinks
Not stated in the README:The README does not specify the ffmpeg-static version, platform coverage, or compatibility with system ffmpeg.;The README does not explain whether failures clearly distinguish yt-dlp, ffmpeg, network, and permission errors.
It depends I maintain a TypeScript/Node.js 18+ tool and want to extend a terminal downloading workflow from an MIT project. I need npm/npx distribution, tsup builds, and a modifiable Ink React UI. Is yoinks a worthwhile base?
For: An open-source developer using TypeScript and Node.js 18+ who wants to build on the project as an npm dependency or customization base

It depends: it is worth considering as a terminal UI and npm CLI prototype, but it should not be treated as a complete downloader or mature release product.

  • The project is written in TypeScript, and its development workflow uses tsup to bundle the code into dist/.
  • The How it works section says the UI uses Ink, React for the terminal, which makes it suitable for extending format selection, status display, and theme interaction.
  • The README supports both npm install -g yoinks and npx yoinks, and the MIT License permits distribution and modification.
  • Download capability primarily comes from yt-dlp, while ffmpeg handles high-resolution merging and MP3 extraction; yoinks mainly orchestrates the workflow.

If you need a stable API, published releases, batch flags, or self-update support, the available project information is insufficient. Script mode and yt-dlp self-update are still roadmap items.

  • Project data: main language TypeScript; MIT License; release_count is 0
  • README “Development”: `npm run build`; bundle to `dist/` with tsup
  • README “How it works”: “The UI is Ink — React for the terminal”
  • README “Install” and “Roadmap”: npm/npx are supported; self-update and script mode are unfinished
npm install
Not stated in the README:The README does not document a stable public TypeScript API, module boundaries, or extension points.;Project data shows no published releases, so compatibility policy, changelogs, and rollback procedures are unknown.;The README does not describe checksum validation, source pinning, or supply-chain verification for fetched binaries.

✨ Highlights

  • Supports YouTube, TikTok, and 1,800+ sites
  • Fetches yt-dlp automatically; Python is not required on first run
  • Ink terminal UI supports both keyboard and mouse control
  • The project has 1 contributor and no releases

🔧 Engineering

  • Use yoinks to paste a URL, choose resolution or mp3, and save to ~/Downloads.
  • Downloads use yt-dlp; ffmpeg handles high-resolution merging and mp3 extraction.
  • Ink provides a full-screen terminal UI with arrows, j/k, number keys, and mouse support.

⚠️ Risks

  • High-resolution merging and mp3 extraction depend on ffmpeg in PATH or ffmpeg-static.
  • The roadmap still marks --best, --mp3, and -o as unfinished.
  • The README warns downloads may violate platform terms and describes yoinks as a personal-archiving tool.
  • With 1 contributor and 0 releases, signals of maintenance maturity are limited.

👥 For who?

  • Developers who need to download YouTube or TikTok videos from a Node 18+ terminal.
  • CLI users who prefer an Ink interface and do not want to install Python.
  • Users who need to quickly run a personal video-archiving tool through npx.