# Pyutube CLI Commands: A Complete Guide to the Download Interface

> Learn Pyutube CLI commands with this guide. Discover the main download command and its flags for audio only, video only, or version display. Enhance your YouTube downloads.

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

---

**Pyutube exposes a single `download` command built with Typer that accepts a YouTube URL and optional flags for audio-only (`-a`), video-only (`-f`), or version display (`-v`), with the entire CLI implementation residing in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py).**

The hetari/pyutube repository provides a streamlined Python tool for downloading YouTube content. Understanding the available Pyutube CLI commands is essential for efficiently grabbing videos, audio tracks, and playlists directly from your terminal.

## The Core Download Command

According to the source code in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) (lines 89–101), Pyutube utilizes the **Typer** framework to expose exactly one top-level command: `download`. When you execute the `pyutube` binary, Typer routes all invocations to this single entry point decorated with `@app.command(name="download")`.

### Command Arguments

The download command requires one positional argument defined in lines 67–86 of [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py):

- **`url_arg`** – The YouTube video, short, or playlist URL to process

### Command Options

The same section (lines 67–86) defines three primary optional flags:

- **`-a`, `--audio`** – Download only the audio track of the video
- **`-f`, `--footage`** – Download only the video stream without audio
- **`-v`, `--version`** – Print the current Pyutube version and exit

## Internal Command Implementation

The runtime logic spanning lines 101–161 in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) orchestrates the download workflow. When invoked, the command first utilizes **`URLHandler`** (from [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py)) to validate the supplied URL and determine its type (standard video, short, or playlist).

Subsequently, the command instantiates **`DownloadService`** (from [`pyutube/services/DownloadService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/DownloadService.py)) to coordinate the actual download process, including pre-parsing metadata and handling audio/video extraction. If no specific flags are provided, the CLI either prompts the user to choose between audio and video or proceeds automatically based on the detected link type.

## Practical Usage Examples

The following commands demonstrate the Pyutube CLI interface:

```bash

# Download a video (interactive mode asks for audio or video selection)

pyutube download https://www.youtube.com/watch?v=abcd1234

# Download only the audio track

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

# or

pyutube download https://www.youtube.com/watch?v=abcd1234 --audio

# Download only the video footage without audio

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

# or

pyutube download https://www.youtube.com/watch?v=abcd1234 --footage

# Display the installed Pyutube version

pyutube download -v

```

## Summary

- Pyutube exposes a **single `download` command** through the Typer framework, defined in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) lines 89–101.
- The command requires a **YouTube URL** argument and supports optional flags for **audio-only** (`-a`), **video-only** (`-f`), and **version** (`-v`) display.
- Internal logic in lines 101–161 coordinates **`URLHandler`** for validation and **`DownloadService`** for the actual download execution.
- When run without flags, the CLI intelligently handles URL types or prompts the user for format selection.

## Frequently Asked Questions

### What is the main command in Pyutube?

Pyutube exposes only one CLI command: `download`. As implemented in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) using the Typer framework, this single entry point handles all YouTube downloads through various optional flags and automatic URL type detection.

### How do I download only audio using Pyutube?

Use the `-a` or `--audio` flag with the download command: `pyutube download <URL> -a`. This option, defined in the CLI arguments section (lines 67–86), routes the request to extract only the audio stream via the `DownloadService` class.

### Where is the CLI logic implemented in the Pyutube source code?

The entire CLI interface is implemented in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py). The Typer application initialization and command definition occupy lines 89–101, argument declarations appear in lines 67–86, and the core execution logic spanning URL validation and service orchestration resides in lines 101–161.

### Does Pyutube support downloading playlists?

Yes. The `URLHandler` class in [`pyutube/handlers/URLHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/URLHandler.py) detects playlist URLs and passes them to `DownloadService`, which processes each item in the playlist sequence according to the selected audio or video options.