# Core Command Flow for Pyutube Downloads: From CLI Argument to Local File

> **When you run `pyutube download <URL>`, the tool executes a ten-step pipeline that parses CLI arguments via Typer, validates connectivity and URLs through `URLHandler`, delegates to a `DownloadService` orchestrator, and branch...

- Repository: [Ebraheem Alhetari/pyutube](https://github.com/hetari/pyutube)
- Tags: 
- Published: 2026-03-03

---

**When you run `pyutube download <URL>`, the tool executes a ten-step pipeline that parses CLI arguments via Typer, validates connectivity and URLs through `URLHandler`, delegates to a `DownloadService` orchestrator, and branches into audio-only, video, or playlist workflows before streaming content to disk via `FileService`.**

The hetari/pyutube repository implements a streamlined command-line interface for YouTube content acquisition. Understanding the core command flow for Pyutube downloads reveals precisely how the tool coordinates CLI parsing, service instantiation, and media processing to deliver files reliably.

## CLI Entry Point and Argument Parsing

The download sequence initiates in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py), where **Typer** constructs the command interface and ingests the YouTube URL, target path, and boolean flags (`--audio`, `--footage`, `--version`).

Before any network activity occurs, the code performs two guard checks. If the user passes `--version`, the program prints the version string and exits immediately via `sys.exit()`. If the URL argument is omitted, Typer raises an error and halts execution. Subsequently, `check_internet_connection()` validates network availability, aborting early when no connection is detected to prevent wasted cycles.

## URL Validation and Classification

Once input sanity is confirmed, the flow delegates to `URLHandler` (defined in [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py)). This utility expands bare video IDs into full canonical URLs and classifies the link type into one of three categories: `video`, `short`, or `playlist`.

Invalid links trigger an immediate exit with an error message. Valid links return a structured handler object that downstream services query to determine which download strategy to invoke.

## Service Orchestration and Download Branching

With a validated URL, the program instantiates a single **DownloadService** object (from [`pyutube/services/DownloadService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/DownloadService.py)) to act as the central orchestrator. This service maintains state for the target URL, destination folder, and quality preferences.

The `DownloadService` evaluates flags and URL type to branch into four distinct execution paths:

- **`--audio` flag**: Forces `download_service.is_audio` to `True`. The service calls `download_preparing()` to fetch video metadata via `pytubefix.YouTube`, then executes `download_audio()` to write the audio stream directly.

- **`--footage` flag or **short** links**: Resolves the requested quality, obtains the video stream through `VideoService.get_video_streams()`, and invokes `download_video()`. This path fetches the video track and, if necessary, a separate audio track, then merges them using `ffmpeg_merge_video_audio`.

- **Plain video links**: Invokes `asking_video_or_audio()` to prompt the user interactively for their preferred format (audio or video), then proceeds along the respective branch listed above.

- **Playlist links**: Calls `DownloadService.get_playlist_links()` to transfer control to **PlaylistHandler** (in [`pyutube/handlers/PlaylistHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/PlaylistHandler.py)). The handler prompts the user for audio/video preference, enumerates all playlist items concurrently, presents a selection interface, optionally enforces ordered filenames (prefixing indices), and iterates over selected IDs by invoking `download()` for each item while preserving the initially selected quality.

## Stream Preparation and File Writing

Regardless of branch, the execution converges on `download_preparing()`, which delegates to `VideoService.search_process()` to instantiate a `pytubefix.YouTube` object, print the video title, and gather adaptive video and audio streams.

**FileService** (located in [`pyutube/services/FileService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/FileService.py)) generates safe filenames, checks for existing files to prevent overwrites, and manages the actual I/O. The method `FileService.save_file()` streams the selected content to disk. In video workflows, after the video file is saved, `download_audio()` fetches the separate audio track, and `VideoService.merging()` combines both streams into a single MP4 container. The process concludes with success messages and a clean `sys.exit()`.

## Practical Usage Examples

The following commands demonstrate how flags trigger specific branches in the core command flow:

```bash

# Interactive mode: prompts for audio vs video selection

pyutube download https://youtu.be/dQw4w9WgXcQ

# Force audio-only extraction

pyutube download https://www.youtube.com/watch?v=dQw4w9WgXcQ -a

# Force video-only (footage) download

pyutube download https://www.youtube.com/watch?v=dQw4w9WgXcQ -f

# Download a full playlist with ordered filenames

pyutube download https://www.youtube.com/playlist?list=PLxxxxxx

```

## Summary

- **Entry Point**: [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) uses Typer to parse arguments and guards against missing URLs or version flags before checking connectivity.
- **Validation**: `URLHandler` in [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py) normalizes URLs and classifies them as video, short, or playlist.
- **Orchestration**: `DownloadService` in [`pyutube/services/DownloadService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/DownloadService.py) instantiates once per command and routes to audio, video, or playlist handlers.
- **Branching**: Flags (`--audio`, `--footage`) and link types determine whether `download_audio()`, `download_video()`, or `PlaylistHandler` manages the workflow.
- **Execution**: `VideoService` interacts with `pytubefix` to fetch streams, while `FileService` writes to disk and `VideoService.merging()` combines separate tracks when required.

## Frequently Asked Questions

### What happens if I run `pyutube download` without providing a URL?

Typer detects the missing required argument in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) and raises a CLI error, causing the program to exit immediately before any network or download logic executes.

### How does Pyutube handle playlists differently from single videos?

When `URLHandler` classifies a link as a playlist, `DownloadService` delegates to `PlaylistHandler` (in [`pyutube/handlers/PlaylistHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/PlaylistHandler.py)), which fetches all video titles concurrently, prompts the user to select specific items, and iterates through the selection while maintaining consistent quality settings across all downloads.

### What is the role of `VideoService` in the download flow?

`VideoService` (in [`pyutube/services/VideoService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/VideoService.py)) encapsulates all interaction with the `pytubefix` library, including `search_process()` to retrieve video metadata, `get_video_streams()` to list available resolutions, and `merging()` to combine separate video and audio files into a final MP4 using `ffmpeg_merge_video_audio`.

### Does Pyutube automatically merge audio and video streams?

Yes. When downloading video content (either via `--footage` or interactive video selection), `DownloadService` calls `FileService.save_file()` for the video stream, then `download_audio()` for the audio stream, and finally `VideoService.merging()` to produce a single container file, ensuring synchronized playback.