Interactive Mode

fetchit's interactive mode is a full-screen terminal interface for downloading media from YouTube, Twitch, and hundreds of other sites. It guides you through every step — from pasting a URL to choosing the right format and watching the download complete in real time. This guide covers every screen, key, and feature in detail.

Launching fetchit

You start the interactive interface by running the fetchit command with no arguments, or by passing a URL directly.

Without a URL

fetchit

When you run fetchit without any arguments, it opens directly to the Input screen. A text field at the top of the terminal awaits a URL. If fetchit detects a valid media link on your clipboard, it shows a hint suggesting you press Tab to paste it. This is the most common way to launch the tool.

With a URL

fetchit "https://youtube.com/watch?v=dQw4w9WgXcQ"

Pass a URL as the first argument to skip the Input screen entirely. fetchit goes straight into the Probing phase, fetching metadata for that link. This is useful when scripting or when you already know what you want to download.

With flags

Several flags modify how the interactive interface behaves at launch:

For a full list of available flags, run fetchit --help.

Screen-by-screen walkthrough

Each time you use fetchit, it moves through a series of phases. Here is what happens on every screen.

1. Input screen

This is the first screen you see when launching without a URL. A clean text field sits at the top with a blinking cursor, ready for a link. Below it, a footer shows available keyboard actions and a compact fetchit logo.

URL field

Type or paste a URL into the field. The supported URL formats include standard YouTube links (youtube.com/watch?v=...), short links (youtu.be/...), Twitch streams and VODs, and URLs from any site yt-dlp supports. The field supports standard text editing keys — see the keyboard reference below for the full list.

Clipboard detection

On launch, fetchit reads your system clipboard. If it finds a string that looks like a media URL (contains youtube.com, twitch.tv, youtu.be, etc.), a subtle hint appears in the footer: "Clipboard: press [Tab] to paste". Press [Tab] to populate the field instantly.

URL history

Once the field has focus, press [↑] and [↓] to cycle through your most recent URLs. The last 50 URLs you downloaded are stored on disk, so history persists across sessions. See the URL history section for details on managing it.

2. Probing phase

After you press [Enter] with a valid URL, fetchit hands the link to yt-dlp to fetch available formats and metadata. This typically takes 1-5 seconds.

What happens

fetchit runs yt-dlp --dump-json in the background. The response includes:

• Video title, uploader, duration, and thumbnail URL
• Every available format — video-only streams, audio-only streams, and combined streams
• For each format: resolution, codec, FPS, bitrate, file size estimate, and format ID
• Chapter markers (if the site provides them)

Progress indicators

A spinner animates in the terminal while probing.

Cancelling

Press [Esc] to cancel the probe and return to the Input screen. This is useful if you pasted the wrong URL or the probe is taking too long.

3. Format picker

Once probing completes, fetchit displays a scrollable list of available formats. The best matches are sorted to the top: recommended combined formats first, then high-resolution video-only streams, then audio-only options. Each row shows metadata about the format so you can make an informed choice.

Understanding format metadata

Each format row displays up to seven columns of information:

The Size column is an estimate based on bitrate and duration. The actual file may differ slightly due to container overhead and variable bitrate encoding. Formats labelled DASH or video only / audio only require muxing — fetchit merges them automatically after download.

Understanding format options

Formats fall into three broad categories. Understanding the trade-offs helps you pick the right one.

• Video + Audio (combined) — A single file containing both video and audio tracks. These are the simplest to use; the file is ready immediately after downloading. They are usually limited to 720p or 1080p on most platforms.
• Video only — High-resolution video without audio. Common for 4K, 60 FPS, or HDR streams. fetchit will automatically download the best matching audio stream and mux them into a single file using ffmpeg.
• Audio only — Just the audio track, typically in opus (webm), m4a (aac), or mp3 format. Useful for music, podcasts, or when you only need the soundtrack.

Codec choices

YouTube and other platforms serve video in several codecs. Each offers different quality-per-bitrate trade-offs:

• av01 — Best compression efficiency, largest playback compatibility gap. Great quality at low bitrates. May not play on older devices.
• vp9 — Excellent compression, widely supported in modern browsers. YouTube's primary codec for 4K content.
• h264 (avc1) — Universal compatibility. Every device can play it, but requires higher bitrates for the same quality as vp9 or av01.

When multiple codecs are available for the same resolution, fetchit sorts av01 above vp9 above h264 — reflecting the best quality-to-size ratio. You are free to pick any option based on your playback needs.

Chapters feature

Press [C] while the format list is focused to toggle chapter embedding. When enabled, fetchit pulls chapter markers from the video metadata and embeds them into the output file. Chapters appear as named timestamps in media players like VLC, MPV, and macOS QuickTime. This feature works on YouTube and any other site that exposes chapter information in yt-dlp's output.

The chapter data is embedded into the file's container metadata — it does not re-encode the video, so there is no quality loss. The toggle state persists for the current session but resets when you start a new download.

Time range clipping

Press [T] in the format picker to open a time-range prompt. You can enter a start and end time to download only a portion of the video. This creates a clip without re-encoding using ffmpeg's fast seek.

Supported time formats:

Limitations

• Time range clipping uses lossless stream copy — it cuts at the nearest keyframe, not at the exact second you specify. The clip may start or end a few frames early or late.
• Some formats (especially DASH streams with separate audio and video) may have slight A/V desync at the cut points. This is rare but depends on the source encoding.
• Time ranges are not compatible with chapter embedding when the range does not align with chapter boundaries.

4. Download phase

After you select a format, fetchit begins downloading. A full-screen progress bar shows real-time status.

Progress bar details

The progress bar fills from left to right as the download progresses. It includes:

• Percentage — complete percentage (e.g. 73%)
• Downloaded / Total — bytes transferred vs. total file size (e.g. 180.2 / 245.3 MiB)
• Speed — current download speed (e.g. 12.5 MiB/s)
• ETA — estimated time remaining (e.g. 00:05)
• Elapsed — time since download started (e.g. 00:14)

For formats that require muxing (e.g. separate DASH video + audio streams), fetchit shows two progress bars sequentially: first the video download, then the audio download, then a brief "Muxing..." step where ffmpeg merges them into the final file.

Cancelling

Press [Esc] to cancel the download at any time. The partially downloaded file is deleted automatically. You return to the format picker to choose again or press [Esc] again to go back to the Input screen.

5. Done screen

When the download completes successfully, fetchit shows a confirmation screen with details about the saved file:

• File path — absolute path to the downloaded file on disk
• File size — final size of the completed file
• Title — the video title for confirmation
• Duration — the length of the downloaded media

Press [Enter] to fetch another URL. This returns you to the Input screen with a fresh URL field. Your history and theme selection persist.

6. Error screen

If something goes wrong at any phase, fetchit displays an error screen with a descriptive message. Common errors include:

• Invalid URL — the URL could not be parsed or is not supported by yt-dlp
• Network error — connection timed out, DNS resolution failed, or the site returned an error
• Format unavailable — the selected format is no longer available (rare, usually means the video was removed or geo-blocked)
• Download failed — the download stream was interrupted mid-transfer
• Muxing failed — ffmpeg could not merge the video and audio streams

Each error screen shows the raw error message from yt-dlp or ffmpeg at the bottom for troubleshooting. Press [Enter] to retry (returning to the Input screen), or [Esc] to quit.

Complete keyboard reference

Every key in fetchit is context-aware. The same key may do different things depending on the active phase. Keys are grouped by category below.

Global keys (all phases)

Input phase

Text editing (URL field)

Probing phase

Format picker phase

Download phase

Done phase

Error phase

Theme system

fetchit ships with three themes — auto, light, and dark. The interface is built with the Bubble Tea framework and respects your terminal's colour capabilities.

Auto mode

When set to auto, fetchit inspects the terminal's background colour using OSC 11 escape sequence queries. If the terminal reports a dark background (brightness below 50% in HSL), the dark theme is applied. Otherwise, the light theme is used. This detection runs once at startup and again each time you cycle to auto via [Ctrl+T].

Auto-detection requires terminal support for the OSC 11 query. Most modern terminals (iTerm2, kitty, WezTerm, Windows Terminal, GNOME Terminal, Alacritty) support it. If the query fails or times out, fetchit defaults to the dark theme.

Light & dark themes

Light mode uses a clean white background with dark text — suitable for well-lit environments. Dark mode uses a near-black background with light text — easier on the eyes in dim lighting and on OLED screens. Both themes use the full 24-bit colour range of your terminal for progress bars, borders, and highlights.

Cycling themes

Press [Ctrl+T] to cycle through auto → light → dark → auto. The current theme is shown briefly in the footer when it changes.

Setting a theme at startup

fetchit --theme dark
fetchit --theme light
fetchit --theme auto

Customizing theme colours

fetchit does not expose individual colour overrides through the CLI. To customize the look, you can configure your terminal's colour scheme — fetchit inherits the foreground, background, and standard ANSI colours from your terminal emulator. For deep customization, consider modifying the base theme definitions in fetchit's source under internal/ui/styles/.

Mouse support

fetchit has full mouse support in terminals that enable the SGR mouse protocol (most modern terminal emulators). Interactive elements detect click events and respond accordingly.

Which terminals support it

Mouse support works in iTerm2, kitty, WezTerm, Windows Terminal, GNOME Terminal, Alacritty, Konsole, and any terminal that sets the TERM environment to xterm-256color or a variant that includes mouse tracking. Raw terminal multiplexers like tmux also support it when configured with set -g mouse on.

What is clickable

• Format rows — click any row in the format picker to select it and immediately start downloading
• fetchit button — on the Input screen, click the styled "fetchit" button to trigger the current URL
• Footer hints — each footer hint (e.g. "[Enter] Fetch") is clickable and triggers the same action as the corresponding key
• Logo — clicking the fetchit logo returns you to the Input screen (acts like pressing [Esc] from most phases)

Mouse support is enabled by default in full-screen mode.

Clipboard detection

On launch, fetchit reads the system clipboard using platform-specific commands:

• macOS — pbpaste
• Linux — xclip -selection clipboard -o or wl-paste (Wayland)
• Windows — PowerShell's Get-Clipboard

If the clipboard content matches a known URL pattern for a supported site, fetchit displays a subtle hint in the footer: "Clipboard: press [Tab] to paste". Pressing [Tab] fills the URL field with the detected link. Clipboard detection only happens at startup — it does not watch for changes while the app is running.

URL history

fetchit keeps a record of your downloaded URLs to make repeat downloads fast.

Viewing history

On the Input screen, use [↑] and [↓] to cycle through previous URLs. The field updates with each entry. History is ordered from most recent to oldest.

Storage location

History is stored in a JSON file on disk:

Clearing history

Deleting the file resets history completely. The file is plain JSON — you can view it with any text editor:

cat ~/.config/fetchit/history.json

The file is capped at 50 entries. When a new URL is added past the limit, the oldest entry is removed automatically.

Config file

fetchit reads configuration from a JSON file on startup. Settings are merged with CLI flags — flags take precedence over the config file.

Location

Available options

Example config

{
  "theme": "dark",
  "download_dir": "~/Downloads/fetchit",
  "max_history": 100,
  "windowed": true,
  "log_level": "warn"
}

Environment variables

fetchit respects the following environment variables:

Tips & power user tricks

Bypass the format picker

If you always want the best quality, use the --best flag. fetchit downloads immediately without showing the picker:

fetchit --best "https://youtube.com/watch?v=..."

Use --mp3 to download only the audio track without interaction.

Quick yt-dlp updates

Press [U] from either the Input screen or the format picker to update yt-dlp to the latest version. fetchit runs yt-dlp --update in the background and shows the result. This is useful when a site changes its API and existing formats fail.

Download to a specific directory

Set a default download directory in the config file, or change it per-session with the FETCHIT_DOWNLOAD_DIR environment variable:

FETCHIT_DOWNLOAD_DIR=~/Movies fetchit "https://youtube.com/watch?v=..."

Check the troubleshooting guide

When a download fails and the error message is not helpful, refer to the troubleshooting guide for common issues and solutions.

Using with tmux

fetchit works inside tmux sessions. Enable mouse support in tmux for clickable elements:

set -g mouse on  # in ~/.tmux.conf

Ensure pass-through mode is enabled for OSC 11 colour queries to work correctly in auto theme mode:

set -g allow-passthrough on  # in ~/.tmux.conf

Resume interrupted downloads

yt-dlp supports partial download resumption. If your download was interrupted, fetch the same URL and format again — yt-dlp automatically resumes where it left off. Note that the progress bar starts from 0% while yt-dlp checks the existing file, then jumps to the actual progress once it confirms the partial data.

Keyboard-driven workflow

For the fastest possible workflow, memorise these three keys:

1. [Tab] — paste clipboard URL (skips typing)
2. [Enter] — probe / download (confirms the current action)
3. [↑] / [↓] — navigate history or format list

With practice, you can go from terminal to downloaded file in under three seconds.

See also

• Scriptable Mode — automate downloads with flags and scripts
• Configuration Reference — all config options in detail
• Troubleshooting — common issues and solutions