CLI Reference

fetchit is a terminal-based video downloader with a rich CLI, an interactive TUI, and a scriptable non-interactive mode. This reference covers every command-line flag, argument, environment variable, exit code, and usage pattern. Whether you are writing a one-liner or integrating fetchit into a pipeline, this page is the canonical source of truth.

Usage & Interactive Command Builder

Use the visual command builder below to generate custom CLI commands for your workflow:

The basic invocation form is:

fetchit [url] [quality] [options]

The url argument is required in non-interactive mode. If omitted, fetchit launches the TUI and prompts for input. The quality argument is optional and can be specified positionally.

Positional Arguments

Options

Exit Codes

fetchit follows UNIX exit code conventions with additional codes for specific error conditions. Scripts and pipelines can inspect the exit code to determine how to handle failures.

Quality Specification

The quality argument (and the underlying --best and --mp3flags) map to yt-dlp format selectors. fetchit simplifies the most common cases so you do not need to learn yt-dlp's format selector syntax for typical use.

Resolution Keywords

When you pass a resolution like 1080p, 720p, 480p, or 360p, fetchit selects the best video stream whose height is at most the given value and merges it with the best available audio stream. If ffmpeg is not installed, only formats that already contain both video and audio are considered (typically lower resolutions).

Format Selection Internals

Under the hood, fetchit translates quality keywords into yt-dlp format selectors. Here is the mapping so you can craft custom selectors if needed via the --ytdl-args passthrough:

You can override format selection entirely by passing raw yt-dlp format selectors:

fetchit --ytdl-args "-f 'bestvideo[codec=avc1]+bestaudio[codec=mp4a}'" https://...

Audio-Only Mode

When mp3 quality or the --mp3 flag is used, fetchit downloads the best available audio stream and transcodes it to MP3 via ffmpeg. If you need a different audio format, use the --ytdl-args passthrough:

# Download as opus (smaller, better quality but less compatible)
fetchit --ytdl-args "-x --audio-format opus" https://...

# Download as flac (lossless, very large)
fetchit --ytdl-args "-x --audio-format flac" https://...

# Download as aac
fetchit --ytdl-args "-x --audio-format aac" https://...

Environment Variables

fetchit reads configuration from environment variables prefixed with FETCHIT_. These variables override the default values but are themselves overridden by CLI flags (CLI flags have the highest priority).

Environment variables are useful when you want to configure fetchit system-wide or in CI/CD pipelines without creating a config file. They are also the only way to configure fetchit in environments where config file access is restricted (e.g., Docker containers).

Configuration File

In addition to CLI flags and environment variables, fetchit reads configuration from JSON files. The configuration hierarchy, from lowest to highest priority, is:

1. Built-in defaults
2. System-wide config at /etc/fetchit/config.json (Unix) or %PROGRAMDATA%\fetchit\config.json (Windows)
3. User config at ~/.fetchit/config.json
4. Project-level config at .fetchitrc in the current working directory
5. Environment variables (FETCHIT_*)
6. CLI flags (highest priority)

Example user configuration file:

{
  "outputDir": "~/videos",
  "defaultQuality": "1080p",
  "concurrency": 5,
  "theme": "dark",
  "flat": false,
  "windowed": false,
  "logLevel": "info",
  "chapters": true
}

Examples

Basic Download

Download a video at the best available quality:

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

Specify Quality

Download at a specific resolution:

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

Audio Extraction

Download a video and extract its audio as an MP3 file:

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

# Equivalent using positional quality argument:
fetchit https://youtube.com/watch?v=dQw4w9WgXcQ mp3

Best Quality Shortcut

Download the absolute best quality available, regardless of resolution:

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

Clip a Section

Download only a specific segment of a video using start and end times:

fetchit --from 1:30 --to 3:45 https://youtube.com/watch?v=dQw4w9WgXcQ

# Using seconds
fetchit --from 90 --to 225 https://youtube.com/watch?v=dQw4w9WgXcQ

Custom Output Directory

Save downloads to a specific folder:

fetchit -o ~/Movies https://youtube.com/watch?v=dQw4w9WgXcQ

# With output template variables
fetchit -o "~/Movies/%(playlist)s/%(title)s.%(ext)s" https://youtube.com/playlist?list=...

Playlist Download

Download an entire playlist. fetchit creates a subfolder for each playlist by default.

fetchit https://youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf

# Skip playlist subfolders
fetchit --flat https://youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf

# Download specific items from a playlist
fetchit --ytdl-args "--playlist-items 1,3,5-7" https://youtube.com/playlist?list=...

Authenticated Downloads

Pass browser cookies to access private videos, age-restricted content, or premium quality streams:

# Use Firefox cookies
fetchit --cookies-from-browser firefox https://youtube.com/watch?v=...

# Use Chrome cookies
fetchit --cookies-from-browser chrome https://youtube.com/watch?v=...

# Use a cookies file (exported via browser extension)
fetchit --ytdl-args "--cookies cookies.txt" https://youtube.com/watch?v=...

Firefox is recommended on Windows when extracting cookies. Chrome and Edge encrypt cookies with platform-level keys that yt-dlp may not be able to decrypt. Firefox stores cookies in plaintext SQLite and works reliably across all platforms.

Parallel Downloads

Increase or decrease the number of concurrent fragment downloads:

# Faster downloads on high-bandwidth connections
fetchit --concurrency 8 https://youtube.com/watch?v=...

# Conservative setting for limited bandwidth
fetchit --concurrency 1 https://youtube.com/watch?v=...

Higher concurrency values can significantly improve download speeds on fast connections but consume more memory and CPU. The default of 3 is a safe starting point. Monitor resource usage if you increase it substantially.

Embed Chapters

Preserve YouTube chapter markers in the downloaded file:

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

Chapters are embedded as MP4/MKV chapter markers. Not all media players support them, but most modern players (VLC, MPV, IINA) do.

Custom yt-dlp and ffmpeg Paths

If you have custom builds of yt-dlp or ffmpeg, point fetchit to them via environment variables:

# PowerShell
$env:FETCHIT_YTDLP_PATH = "C:	oolsyt-dlp.exe"
$env:FETCHIT_FFMPEG_PATH = "C:	oolsfmpeg.exe"
fetchit https://youtube.com/watch?v=dQw4w9WgXcQ

# Bash
export FETCHIT_YTDLP_PATH=/opt/yt-dlp-custom
export FETCHIT_FFMPEG_PATH=/opt/ffmpeg-custom
fetchit https://youtube.com/watch?v=dQw4w9WgXcQ

Theme Selection

Force a specific color theme for the TUI:

fetchit --theme light https://youtube.com/watch?v=...
fetchit --theme dark https://youtube.com/watch?v=...

# Let fetchit follow the system theme
fetchit --theme auto https://youtube.com/watch?v=...

Download from Clipboard

When launched without arguments, fetchit opens the TUI and optionally detects a YouTube URL from the system clipboard:

fetchit

The TUI prompts you to paste a URL or confirms the one detected from the clipboard. This is the fastest way to download when you already have a URL copied.

Non-Interactive / Scriptable Mode

When stdout is not a terminal (piped, redirected, or run in CI), fetchit automatically disables the TUI and behaves as a pure CLI tool. This makes it suitable for scripting and automation:

# In a shell script
fetchit https://youtube.com/watch?v=dQw4w9WgXcQ 720p -o ~/downloads > /dev/null

# Capture the output filename (if yt-dlp supports --print after download)
fetchit --ytdl-args "--print after_move:filepath" https://...

Using Behind a Proxy

fetchit passes proxy settings directly to yt-dlp:

fetchit --ytdl-args "--proxy http://127.0.0.1:8080" https://...

# SOCKS5 proxy
fetchit --ytdl-args "--proxy socks5://127.0.0.1:1080" https://...

Rate Limit Workaround

If you hit YouTube rate limits, add a delay between requests and provide browser cookies:

fetchit --cookies-from-browser firefox --ytdl-args "--sleep-interval 30" https://youtube.com/playlist?list=...

Download Only Subtitles

You can download subtitles or closed captions instead of video:

fetchit --ytdl-args "--write-subs --sub-lang en --skip-download" https://...

Custom Output Template

Use yt-dlp output template variables for fine-grained file naming:

# Use video ID and upload date
fetchit -o "%(upload_date)s - %(title)s.%(ext)s" https://...

# Limit title length (Windows path length workaround)
fetchit -o "%(title).100B.%(ext)s" https://...

Checking the Version

Print the currently installed fetchit version and exit:

fetchit --version

Getting Help

Print a summary of all available flags:

fetchit --help

Shell Completions

fetchit provides shell completion scripts for Bash, Zsh, and Fish. These are typically installed automatically when you install fetchit via npm, but can be manually sourced if needed.

To enable completions for your current shell:

# Bash — add to ~/.bashrc
source <(fetchit completion bash)

# Zsh — add to ~/.zshrc
source <(fetchit completion zsh)

# Fish — add to ~/.config/fish/config.fish
fetchit completion fish | source

Completions provide tab-completion for URLs (from history), quality keywords, flags, and flag arguments (e.g., theme names, log levels).

Signal Handling

fetchit handles the following POSIX signals to ensure clean shutdown and avoid leaving partial files:

Exit Code Usage in Scripts

The exit codes are designed to be actionable in shell scripts. Here is a common pattern:

fetchit https://youtube.com/watch?v=... 1080p
case $? in
  0) echo "Download succeeded" ;;
  2) echo "Bad arguments — check your syntax" ;;
  3) echo "Network error — check your connection" ;;
  4) echo "ffmpeg is required for this operation" ;;
  5) echo "yt-dlp failed — run with --verbose" ;;
  6) echo "Rate limited — use cookies or a VPN" ;;
  130) echo "User cancelled" ;;
  *) echo "Unknown error ($?)" ;;
esac

In CI/CD pipelines, consider retrying on exit codes 3 (network) and 6 (rate limit), as these are typically transient.

Global Flags

The following flags are available on every invocation and must appear before any positional arguments:

All other flags can appear in any order, but positional arguments must appear in the order shown in the usage line: fetchit [url] [quality] [options].

Pass-Through Arguments

Any argument prefixed with --ytdl-argsis passed verbatim to yt-dlp. This gives you access to the full power of yt-dlp while keeping fetchit's interface simple. Some useful passthrough options:

Best Practices

• Always use --verbose when reporting bugs. The verbose output contains the exact yt-dlp command, its full output, and internal fetchit state. This is the single most helpful piece of information for debugging.
• Set FETCHIT_YTDLP_PATH in CI/CD to pin a specific yt-dlp version and avoid unexpected breakage from automatic updates.
• Use --flat for playlist downloads in scripts to guarantee a predictable output structure (no nested subdirectories).
• Prefer --cookies-from-browser over cookie files for security. Cookie files store credentials in plaintext.
• Set FETCHIT_THEME=dark in your shell profile if you consistently prefer the dark theme, so you do not need to pass --theme every time.
• Use --best or --mp3 in cron jobs or CI to avoid the interactive TUI. Override to --best temporarily when troubleshooting.
• Run fetchit doctor to verify your environment when something does not work as expected. It checks for yt-dlp, ffmpeg, PATH configuration, and common misconfigurations.