yoinks: a terminal video downloader built on yt-dlp and Ink

The problem yoinks targets: ad-laden download pages

Search for a video downloader and you get a wall of pages with fake download buttons, redirect chains and popups. The README states the project's pitch plainly: "No popups, no fake download buttons, no sketchy redirects." That is the whole product thesis. It is not trying to be a better yt-dlp; it is trying to be the thing a non-CLI-expert reaches for instead of a browser site.

The intended user is someone who is comfortable in a terminal but does not want to memorise yt-dlp's format-selection syntax. yt-dlp already downloads from the same sites, but picking a specific resolution means knowing the -f flag grammar and reading a format table. yoinks replaces that with a full-screen picker listing resolutions with estimated file sizes plus an audio-only mp3 option, per the README's screenshot caption.

Scope is broad by inheritance rather than by the author's own work: the README claims YouTube, X/Twitter, Instagram, Threads, TikTok and "1,800+ other sites." That number comes from yt-dlp's extractor list, not from code in this repository. If a site breaks, the fix usually lands in yt-dlp, not here, which is worth understanding before you file an issue against yoinks.

How yoinks works: an Ink front end over a bundled yt-dlp

The architecture is a thin interactive layer. The README says the UI is Ink, described there as "React for the terminal," and package.json confirms the stack: ink ^7.1.0, ink-select-input, ink-spinner and react ^19.2.7 as runtime dependencies. So the picker is a React component tree rendered to a terminal, not a curses or readline implementation.

The download engine is yt-dlp. On first run, according to the README, yoinks downloads the standalone yt-dlp binary to ~/.yoinks/bin, and no Python is required. If you already have yt-dlp installed, it uses yours instead. That ordering matters: a system yt-dlp takes precedence, so a stale one on your PATH is the one yoinks will call.

ffmpeg is resolved differently. The README says it is found on your PATH, with ffmpeg-static as a bundled fallback, and package.json lists ffmpeg-static ^5.3.0 as a dependency. That fallback is why the npm package can promise that "everything else" is fetched or bundled automatically. ffmpeg is not optional here: the README names merging high-resolution streams and mp3 extraction as the two jobs it does, and both are ffmpeg operations.

Data flow is linear. A URL comes in as an argument or from a prompt, yt-dlp resolves available formats, the Ink picker renders them, your selection goes back to yt-dlp, and the finished file path is printed to your terminal. Files land in ~/Downloads.

Installing yoinks and running a first download

The README gives two install paths. The global one makes yoinks available as a command:

npm install -g yoinks

If you would rather not install anything, the README offers a one-shot run through npx:

npx yoinks

Node 18 or higher is required; package.json sets engines.node to ">=18". Everything else is handled for you, per the README.

To download something, pass the URL as an argument. The README's own example goes straight to the format picker:

yoinks https://youtu.be/dQw4w9WgXcQ

Run it bare and it prompts for a URL instead. Inside the picker, the README documents arrow keys or j/k or number keys to move, enter to select, esc to go back and Ctrl-C to quit. Mouse input works too: the yoink button, the format list and the footer hints are clickable. When the download finishes, the file path is printed to your terminal, and the file sits in ~/Downloads.

There is one display flag. The README shows --theme with auto, light or dark, and notes you can also press Ctrl-T or click the footer control to cycle themes for the current session:

yoinks --theme light

The default auto theme uses your terminal's own foreground and background, so it follows a light or dark terminal without guessing.

What yoinks cannot do yet: no scriptable mode, no output flag

The README's roadmap is the most useful part of the documentation, because it lists what is missing. Scriptable mode is unchecked: "--best / --mp3 flags to skip the picker." Output directory selection is unchecked: "-o <dir> to choose the output folder." Playlist and multi-video thread support is unchecked.

Those are not cosmetic gaps. Without --best or --mp3, yoinks is interactive by design, so it does not fit a cron job, a shell pipeline or any unattended download. Without -o, every file goes to ~/Downloads and you move it afterward yourself. If your workflow is "download this 40-item playlist overnight," yoinks is the wrong tool today and yt-dlp directly is the right one.

The bundled yt-dlp also has no self-update path yet. The roadmap lists "Self-update for the bundled yt-dlp binary (yt-dlp -U)" as unchecked, which means the binary yoinks fetches into ~/.yoinks/bin does not refresh itself through yoinks. When an extractor breaks, you either update your own yt-dlp or remove the cached binary so yoinks fetches a fresh one. The README does not document that removal procedure.

Finally, the project is a personal-archiving tool by its own description. The README's fair-use note says downloading content may violate a platform's terms of service. That is a real constraint on where you deploy this, not a disclaimer to skim.

yoinks versus calling yt-dlp directly

The honest alternative is yt-dlp itself, and the difference is interface, not capability. Both reach the same sites, because yoinks delegates extraction entirely to yt-dlp. What yoinks adds is the picker: resolutions with estimated file sizes, an mp3 option, and clickable controls, all rendered through Ink.

What yt-dlp keeps that yoinks does not expose is the flag surface. Format selection, output templates, playlist ranges, cookies, rate limits, subtitles and post-processing are all reachable from the command line and none of them are surfaced in yoinks' UI. If you need any of that, yoinks is a detour.

The trade-off runs the other way too. yt-dlp asks you to know what you want before you type. yoinks asks you to look at a list and choose. For a one-off download of a video you have not inspected, the picker is faster than reading yt-dlp's format table and guessing which ID is the 1080p muxed stream. For a repeatable job, the picker is an obstacle.

A secondary difference is distribution. yt-dlp is a Python project or a standalone binary depending on how you get it. yoinks is an npm package with a Node 18 floor, and it will use your existing yt-dlp if one is on your PATH. That means yoinks is not a replacement for a yt-dlp install in most setups; it is a front end that assumes one is either present or fetchable.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-07-17. The published version in package.json is 0.3.1, and the prepublishOnly script runs tests, typecheck and build before any publish, so releases are gated on npm test, npm run typecheck and npm run build passing.

The upgrade cost is low on the yoinks side and higher underneath it. Upgrading yoinks is an npm operation, but the two binaries it depends on move independently. yt-dlp needs frequent updates because site extractors break; ffmpeg changes less often. The README does not document how to refresh the yt-dlp binary that yoinks caches in ~/.yoinks/bin, and the roadmap lists self-update as unfinished. Budget for that gap: when downloads start failing on a site that used to work, yt-dlp is the first thing to check, not yoinks.

Licensing is MIT, stated in both the README and the LICENSE file at the repository root. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That covers yoinks' own code. It does not cover the content you download, and it does not automatically describe the licence terms of the bundled ffmpeg-static binary or of yt-dlp, which are separate projects with their own terms. This is not legal advice; check those projects if redistribution matters to you.

Editorial conclusion

Adopt yoinks if you already work in a terminal, want yt-dlp's site coverage without memorising its flags, and are comfortable with an interactive picker rather than a scriptable command. Do not adopt it if you need unattended downloads, playlist or thread support, or a chosen output directory, because the README's roadmap lists all three as unchecked. Before installing, confirm your Node version is 18 or higher, check that npm install -g yoinks resolves version 0.3.1, and decide whether you want yoinks to fetch its own yt-dlp binary into ~/.yoinks/bin or to use one already on your PATH.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pablostanley/yoinks on GitHub
4. README