Pyutube CLI Commands: A Complete Guide to the Download Interface

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.

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 (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:

• 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 orchestrates the download workflow. When invoked, the command first utilizes URLHandler (from 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) 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:

# 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 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 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. 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 detects playlist URLs and passes them to DownloadService, which processes each item in the playlist sequence according to the selected audio or video options.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}