yoinks: The terminal video downloader that feels more like a tiny app than a wrapper

A deep look at how yoinks uses Ink, yt-dlp, clipboard automation, and a few sharp TUI tricks to make “paste, yoink, done” feel genuinely polished.

8-10 min read • View on GitHub • More from pablostanley

A wide terminal window presented like a polished control panel, with a pasted URL in an input field, selectable format rows, and a download progress area. It explains the article's core idea: a command-line tool can still feel curated, legible, and product-like.
yoinks turns a common terminal task into something that feels designed, not merely assembled.
Key Takeaways

The first surprise is not that yoinks downloads video. It is that the terminal opens like a small, deliberate app. The clipboard can prefill the URL, the interface takes over the screen, and the whole flow feels closer to a polished desktop utility than a script with a prompt.

That is the point. yoinks is built on top of yt-dlp, but the wrapper is where the product lives. It narrows a huge search space into a few obvious moves: paste a link, inspect formats, pick one, download it, leave.

A WSJ-style editorial portrait of Pablo Stanley, the project owner, rendered in black ink on a pure white background. It establishes authorship and gives the article a human anchor without inventing any new likeness details.

Why this downloader feels different the moment you launch it

Most download tools front-load choice. Yoinks does the opposite. It enters the terminal's alternate screen, focuses on a single task, and makes the first interaction feel like a complete workflow rather than an argument with flags.

That line captures the project's tone. Secondary features are welcome, but they never get permission to derail the main job. The result is a tool that feels calm under pressure, which matters more than raw feature count when the task is operational and repetitive.

yoinks fakes native mouse support by mapping rendered terminal text back to click coordinates.

WorkflowFirst-run frictionFormat selectionCancelabilityMouse supportOverall feel
Raw yt-dlp in the terminalLow if you already know the flags, high if you do notFully manual and verboseDepends on how you launch itNoPowerful, but spiky
Browser download workflowLow to start, then clutteredOften hidden behind web UI churnUsually poor once the flow beginsYes, but only in the browserFamiliar, but noisy
yoinksLow, because it pre-fills and guidesCurated into human-readable choicesBuilt in with Esc and AbortControllerYes, via hit-testingConstrained, polished, terminal-native

The shell is the product

Under the hood, yoinks is a chain of decisions about what to show and when to hide it. The codebase is modular, but the important move is upstream: probe first, then present a curated set of choices, then turn the chosen option back into a yt-dlp invocation.

type Phase = 'input' | 'probing' | 'picking' | 'downloading' | 'done' | 'error'

// The app moves forward in one direction.
// Each phase narrows the user's next decision.

That state machine is the product skeleton. It keeps the terminal from feeling slippery. Once the app is in a phase, there is a small and understandable set of actions available, which is exactly what a good TUI should do.

The format picker is the clearest example. Raw yt-dlp output is rich but noisy. yoinks translates it into legible labels like 1080p · mp4, often with estimated sizes, so the user is choosing from meaningful options instead of parsing codec trivia.

LayerRaw tool behavioryoinks behavior
DiscoveryProbe and read JSON yourselfProbe once, cache the result, and present a menu
FormatsDozens of technical variantsA smaller set of human-readable choices
ControlEverything is exposedOnly the useful subset is surfaced

How the app stays predictable

The reliability story is boring in the best way. yoinks uses AbortController so Escape can stop a long-running process, and it treats error states as bounded instead of catastrophic. You do not need a fresh terminal session just to recover from a bad input.

const controller = new AbortController()

// When the user presses Esc:
controller.abort()

// The running yt-dlp process is stopped without tearing down the whole app.

That predictability matters because the app is doing several things at once: probing metadata, resolving formats, managing clipboard input, and sometimes downloading helper binaries. The trick is that none of those support tasks gets to redefine the core loop.

The cleverest trick: clickable text in a TUI

This is the part of the repo that feels most inventive. Ink does not hand you true component coordinates, so yoinks builds its own map of what was rendered, strips ANSI codes, and compares mouse coordinates against the text frame.

A close-up terminal screen is shown in layers, with colored output on top, a plain-text capture grid beneath it, and a cursor position resolving to a text target. It explains how yoinks turns mouse clicks into actions by matching screen coordinates to rendered strings.
The mouse does not click a component. It clicks a mapped patch of rendered text.

That workaround does two things. First, it gives the UI mouse affordances without giving up the terminal. Second, it keeps the mental model simple: visible text is still the source of truth, which means the click target and the thing you see stay tightly aligned.

Why it never lets a side feature break the download

The repo shows a strong bias toward graceful failure. History can fail quietly. Theme detection can stay conservative. Clipboard support can help when available and disappear when it is not. The main job still completes.

That discipline is what makes yoinks feel mature. Plenty of tools advertise polish. Fewer define polish as a refusal to let optional niceties become failure points.

Secondary featureIf it failsUser impact
HistorySilently ignoredNone on the download path
Clipboard prefillUser types the URL manuallySmall inconvenience, not a blocker
Theme auto-detectionTerminal defaults take overThe interface stays usable
Binary bootstrappingFallback path may kick inThe app still reaches the main task

终端里下一个工具:Yoinks。 YouTube、X、TikTok,以及 1800+ 站点的视频,一条命令拉下来。 作者 @pablostanley,基于熟悉的下载生态,但包装成更好用的 terminal app。 经常存素材的人,会喜欢这种「少开浏览器」的路径。 https://t.co/5T1LHlT6UC

iluciddreaming, X community post · @iluciddreaming on X

What yoinks is really for

yoinks is not trying to replace every downloader workflow. It is trying to make one common workflow pleasant: grab a link, inspect a few good options, and get out. That makes it a strong fit for people who archive media often, care about keyboard-first speed, and want fewer browser tabs in the loop.

Compared with raw yt-dlp, it hides complexity. Compared with browser-first downloaders, it removes clutter. Compared with a generic TUI wrapper, it offers actual product thinking. That is the sweet spot.