CLI Commands Reference ====================== Pytubekit provides a single entry point (``pytubekit``) with multiple subcommands (endpoints). Each endpoint accepts configuration parameters that can be passed via command-line arguments. .. _listing--info: Listing / Info -------------- ``get_channel_id`` ~~~~~~~~~~~~~~~~~~ Show your YouTube channel ID, or with ``--watch-later``, show the Watch Later playlist ID. .. code:: bash # Get channel ID pytubekit get_channel_id # Get Watch Later playlist ID pytubekit get_channel_id --watch-later **Parameters:** +--------------------------+------+---------+------------------------------------------------------+ | Parameter | Type | Default | Description | +==========================+======+=========+======================================================+ | ``--watch-later`` | bool | False | Output Watch Later playlist ID instead of channel ID | +--------------------------+------+---------+------------------------------------------------------+ -------------- ``playlist`` ~~~~~~~~~~~~ List all entries in a specific playlist. .. code:: bash pytubekit playlist --name "My Playlist" pytubekit playlist --playlist-id PLxxxxxxxx pytubekit playlist --name "My Playlist" --full **Parameters:** +--------------------------+------+---------+--------------------------------------------+ | Parameter | Type | Default | Description | +==========================+======+=========+============================================+ | ``--name`` | str | None | Playlist name to look up | +--------------------------+------+---------+--------------------------------------------+ | ``--playlist-id`` | str | None | Playlist ID to use directly | +--------------------------+------+---------+--------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +--------------------------+------+---------+--------------------------------------------+ | ``--full`` | bool | False | Output full JSON instead of just video IDs | +--------------------------+------+---------+--------------------------------------------+ Provide either ``--name`` or ``--playlist-id``, not both. -------------- ``video_info`` ~~~~~~~~~~~~~~ Get detailed information about a specific video (snippet, status, content details). .. code:: bash pytubekit video_info --id xL_sMXfzzyA **Parameters:** ========= ==== ========== ================ Parameter Type Default Description ========= ==== ========== ================ ``--id`` str (required) YouTube video ID ========= ==== ========== ================ -------------- ``channels`` ~~~~~~~~~~~~ List your channels and their playlists with full details (snippet, content details, statistics). .. code:: bash pytubekit channels No additional parameters. -------------- ``find_video`` ~~~~~~~~~~~~~~ Find which playlists (or dump files) contain a given video. By default, queries the YouTube API. With ``--local-dump-folder``, searches local dump files instead (zero API quota). .. code:: bash # API mode: search YouTube playlists pytubekit find_video --find-video-id dQw4w9WgXcQ # Local mode: search dump files (zero API quota) pytubekit find_video --find-video-id dQw4w9WgXcQ --local-dump-folder /path/to/dump **Parameters:** +-------------------------+------+------------+-----------------------------------------------------+ | Parameter | Type | Default | Description | +=========================+======+============+=====================================================+ | ``--find-video-id`` | str | (required) | YouTube video ID to search for | +-------------------------+------+------------+-----------------------------------------------------+ | ``--local-dump-folder`` | str | ``.`` | Path to dump folder (if not ``.``, uses local mode) | +-------------------------+------+------------+-----------------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination (API mode only) | +-------------------------+------+------------+-----------------------------------------------------+ -------------- ``stats`` ~~~~~~~~~ Show statistics for playlists (or dump files): each name with its item count, then totals (count, total items, largest, smallest). By default, shows all playlists. Use ``--stats-names`` to filter to specific playlists. With ``--local-dump-folder``, reads local dump files instead (zero API quota). .. code:: bash # API mode: all playlists pytubekit stats # API mode: specific playlists only pytubekit stats --stats-names "Music" "Talks" # Local mode: count lines in dump files (zero API quota) pytubekit stats --local-dump-folder /path/to/dump # Local mode: specific files only pytubekit stats --local-dump-folder /path/to/dump --stats-names "Music" "Talks" **Parameters:** +-------------------------+-----------+---------+-----------------------------------------------------+ | Parameter | Type | Default | Description | +=========================+===========+=========+=====================================================+ | ``--stats-names`` | list[str] | ``[]`` | Filter to these playlist/file names (omit for all) | +-------------------------+-----------+---------+-----------------------------------------------------+ | ``--local-dump-folder`` | str | ``.`` | Path to dump folder (if not ``.``, uses local mode) | +-------------------------+-----------+---------+-----------------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination (API mode only) | +-------------------------+-----------+---------+-----------------------------------------------------+ -------------- ``search_playlist`` ~~~~~~~~~~~~~~~~~~~ Search for videos by title or channel name across playlists (API mode), or search video IDs in dump files (local mode). With ``--local-dump-folder``, searches local dump files with zero API quota. .. code:: bash # API mode: search YouTube playlists by title/channel pytubekit search_playlist --search-playlists "Music" "Talks" --search-query "python" # Local mode: search dump files by video ID (zero API quota) pytubekit search_playlist --search-query "dQw4" --local-dump-folder /path/to/dump **Parameters:** +-------------------------+-----------+-------------------------+-----------------------------------------------------+ | Parameter | Type | Default | Description | +=========================+===========+=========================+=====================================================+ | ``--search-playlists`` | list[str] | (required for API mode) | Playlist names to search in | +-------------------------+-----------+-------------------------+-----------------------------------------------------+ | ``--search-query`` | str | (required) | Text to search for | +-------------------------+-----------+-------------------------+-----------------------------------------------------+ | ``--local-dump-folder`` | str | ``.`` | Path to dump folder (if not ``.``, uses local mode) | +-------------------------+-----------+-------------------------+-----------------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination (API mode only) | +-------------------------+-----------+-------------------------+-----------------------------------------------------+ -------------- .. _export--backup: Export / Backup --------------- ``dump`` ~~~~~~~~ Dump all playlists to files in a folder. Each playlist is saved as a separate file named after the playlist title, containing video IDs (or full JSON if ``--full`` is set). .. code:: bash pytubekit dump --dump-folder /path/to/output pytubekit dump --dump-folder '${home}/youtube-backup/${date}' The ``--dump-folder`` parameter supports template substitution: - ``${date}`` - current Unix timestamp - ``${home}`` - user's home directory **Parameters:** +--------------------------+------+---------+--------------------------------------------+ | Parameter | Type | Default | Description | +==========================+======+=========+============================================+ | ``--dump-folder`` | str | ``.`` | Folder to dump playlists into | +--------------------------+------+---------+--------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +--------------------------+------+---------+--------------------------------------------+ | ``--full`` | bool | False | Output full JSON instead of just video IDs | +--------------------------+------+---------+--------------------------------------------+ -------------- ``export_csv`` ~~~~~~~~~~~~~~ Export a playlist to CSV with video ID, title, channel, and position. .. code:: bash pytubekit export_csv --export-playlist-name "Music" --export-csv-path music.csv **Parameters:** ========================== ==== ========== ============================ Parameter Type Default Description ========================== ==== ========== ============================ ``--export-playlist-name`` str (required) Name of playlist to export ``--export-csv-path`` str (required) Path to CSV file to write ``--page-size`` int 50 Page size for API pagination ========================== ==== ========== ============================ Output columns: ``position``, ``video_id``, ``title``, ``channel``. -------------- ``collect_ids`` ~~~~~~~~~~~~~~~ Extract YouTube video IDs from text files. .. code:: bash pytubekit collect_ids --collect-files notes.txt bookmarks.html **Parameters:** +----------------------+-----------+------------+-------------------------------------+ | Parameter | Type | Default | Description | +======================+===========+============+=====================================+ | ``--collect-files`` | list[str] | (required) | Files to scan for YouTube video IDs | +----------------------+-----------+------------+-------------------------------------+ Prints unique video IDs found across all input files. -------------- ``add_data`` ~~~~~~~~~~~~ Fetch extensive metadata for a list of video IDs and write to CSV. Supports resuming from a previous run (skips IDs already present in the output CSV). .. code:: bash pytubekit add_data --input-file ids.txt --output-csv metadata.csv **Parameters:** +------------------+------+------------+-------------------------------------------------+ | Parameter | Type | Default | Description | +==================+======+============+=================================================+ | ``--input-file`` | str | (required) | Path to text file with video IDs (one per line) | +------------------+------+------------+-------------------------------------------------+ | ``--output-csv`` | str | (required) | Path to CSV file to write metadata to | +------------------+------+------------+-------------------------------------------------+ -------------- ``diff`` ~~~~~~~~ Compute set difference (A-B) or intersection (A&B) between video ID sources. Sources can be YouTube playlists or local files. .. code:: bash # Playlists vs files: videos in playlists but not in local files pytubekit diff --diff-a-playlists "All" --diff-b-files seen.txt # Playlists vs playlists: videos in "All" but not in "Watched" pytubekit diff --diff-a-playlists "All" --diff-b-playlists "Watched" # Files vs files: videos in file A but not in file B pytubekit diff --diff-a-files all.txt --diff-b-files seen.txt # Intersection instead of difference pytubekit diff --diff-a-playlists "All" --diff-b-files seen.txt --diff-reverse # Write to file instead of stdout pytubekit diff --diff-a-playlists "All" --diff-b-files seen.txt --diff-output-file unseen.txt **Parameters:** +------------------------+-----------+---------+-------------------------------------------------------------+ | Parameter | Type | Default | Description | +========================+===========+=========+=============================================================+ | ``--diff-a-playlists`` | list[str] | ``[]`` | Source A: YouTube playlist names | +------------------------+-----------+---------+-------------------------------------------------------------+ | ``--diff-a-files`` | list[str] | ``[]`` | Source A: local files with video IDs | +------------------------+-----------+---------+-------------------------------------------------------------+ | ``--diff-b-playlists`` | list[str] | ``[]`` | Source B: YouTube playlist names | +------------------------+-----------+---------+-------------------------------------------------------------+ | ``--diff-b-files`` | list[str] | ``[]`` | Source B: local files with video IDs | +------------------------+-----------+---------+-------------------------------------------------------------+ | ``--diff-reverse`` | bool | False | ``False`` = A-B (difference), ``True`` = A&B (intersection) | +------------------------+-----------+---------+-------------------------------------------------------------+ | ``--diff-output-file`` | str | None | Path to write results (omit for stdout) | +------------------------+-----------+---------+-------------------------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +------------------------+-----------+---------+-------------------------------------------------------------+ -------------- Cleanup ------- .. _cleanup-1: ``cleanup`` ~~~~~~~~~~~ Clean up playlists by removing duplicates, deleted videos, and/or private videos. By default, targets all playlists. Use ``--cleanup-names`` to filter to specific playlists. .. code:: bash # Clean up all playlists pytubekit cleanup # Clean up specific playlists pytubekit cleanup --cleanup-names "Playlist1" "Playlist2" # Skip deduplication pytubekit cleanup --cleanup-names "My Playlist" --no-dedup # Dry run (report only) pytubekit cleanup --no-do-delete **Parameters:** +-----------------------+-----------+---------+-------------------------------------------------------+ | Parameter | Type | Default | Description | +=======================+===========+=========+=======================================================+ | ``--cleanup-names`` | list[str] | ``[]`` | Playlist names to clean up (omit for all) | +-----------------------+-----------+---------+-------------------------------------------------------+ | ``--dedup`` | bool | True | Detect and remove duplicate entries | +-----------------------+-----------+---------+-------------------------------------------------------+ | ``--deleted`` | bool | True | Remove deleted videos | +-----------------------+-----------+---------+-------------------------------------------------------+ | ``--privatized`` | bool | True | Remove private videos | +-----------------------+-----------+---------+-------------------------------------------------------+ | ``--do-delete`` | bool | True | Actually perform deletions (set to False for dry run) | +-----------------------+-----------+---------+-------------------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +-----------------------+-----------+---------+-------------------------------------------------------+ -------------- Playlist Operations ------------------- ``create_playlist`` ~~~~~~~~~~~~~~~~~~~ Create a new playlist with a given name, description, and privacy status. .. code:: bash pytubekit create_playlist --create-name "My New Playlist" pytubekit create_playlist --create-name "Private List" --create-description "Personal videos" --create-privacy private **Parameters:** +--------------------------+------+------------+----------------------------------------------------------+ | Parameter | Type | Default | Description | +==========================+======+============+==========================================================+ | ``--create-name`` | str | (required) | Name for the new playlist | +--------------------------+------+------------+----------------------------------------------------------+ | ``--create-description`` | str | ``""`` | Description for the new playlist | +--------------------------+------+------------+----------------------------------------------------------+ | ``--create-privacy`` | str | ``public`` | Privacy status: ``public``, ``unlisted``, or ``private`` | +--------------------------+------+------------+----------------------------------------------------------+ -------------- ``delete_playlist`` ~~~~~~~~~~~~~~~~~~~ Delete a playlist by name. .. code:: bash pytubekit delete_playlist --delete-playlist-name "Old Playlist" **Parameters:** +----------------------------+------+------------+--------------------------------+ | Parameter | Type | Default | Description | +============================+======+============+================================+ | ``--delete-playlist-name`` | str | (required) | Name of the playlist to delete | +----------------------------+------+------------+--------------------------------+ -------------- ``subtract`` ~~~~~~~~~~~~ Subtract one set of playlists from another. Finds videos present in both sets and removes them from the "subtract from" playlists. .. code:: bash pytubekit subtract --subtract-what "Watched" --subtract-from "To Watch" **Parameters:** +----------------------+-----------+------------+---------------------------------------------+ | Parameter | Type | Default | Description | +======================+===========+============+=============================================+ | ``--subtract-what`` | list[str] | (required) | Playlist names containing items to subtract | +----------------------+-----------+------------+---------------------------------------------+ | ``--subtract-from`` | list[str] | (required) | Playlist names to subtract from | +----------------------+-----------+------------+---------------------------------------------+ | ``--do-delete`` | bool | True | Actually perform deletions | +----------------------+-----------+------------+---------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +----------------------+-----------+------------+---------------------------------------------+ -------------- ``merge`` ~~~~~~~~~ Merge or copy playlists into a destination playlist. By default, deduplicates (skips videos already in destination). Use ``--no-merge-dedup`` to copy all videos without deduplication. .. code:: bash # Merge with deduplication (default) pytubekit merge --merge-sources "Rock" "Pop" --merge-destination "All Music" # Copy without deduplication (like old copy_playlist) pytubekit merge --merge-sources "Original" --merge-destination "Backup" --no-merge-dedup **Parameters:** +-------------------------+-----------+------------+-----------------------------------------+ | Parameter | Type | Default | Description | +=========================+===========+============+=========================================+ | ``--merge-sources`` | list[str] | (required) | Source playlist names to merge from | +-------------------------+-----------+------------+-----------------------------------------+ | ``--merge-destination`` | str | (required) | Destination playlist name to merge into | +-------------------------+-----------+------------+-----------------------------------------+ | ``--merge-dedup`` | bool | True | Skip duplicates already in destination | +-------------------------+-----------+------------+-----------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +-------------------------+-----------+------------+-----------------------------------------+ -------------- ``sort_playlist`` ~~~~~~~~~~~~~~~~~ Sort a playlist by title, channel, or date. This deletes and re-adds all items in sorted order. .. code:: bash pytubekit sort_playlist --sort-playlist-name "Music" --sort-key title pytubekit sort_playlist --sort-playlist-name "Music" --sort-key channel pytubekit sort_playlist --sort-playlist-name "Music" --sort-key date **Parameters:** +--------------------------+------+------------+-----------------------------------------------+ | Parameter | Type | Default | Description | +==========================+======+============+===============================================+ | ``--sort-playlist-name`` | str | (required) | Name of playlist to sort | +--------------------------+------+------------+-----------------------------------------------+ | ``--sort-key`` | str | ``title`` | Sort key: ``title``, ``channel``, or ``date`` | +--------------------------+------+------------+-----------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +--------------------------+------+------------+-----------------------------------------------+ .. warning:: Sorting deletes all items from the playlist and re-adds them in order. This consumes significant API quota. -------------- ``rename_playlist`` ~~~~~~~~~~~~~~~~~~~ Rename a playlist. .. code:: bash pytubekit rename_playlist --rename-playlist-name "Old Name" --rename-new-name "New Name" **Parameters:** ========================== ==== ========== ============================ Parameter Type Default Description ========================== ==== ========== ============================ ``--rename-playlist-name`` str (required) Current name of the playlist ``--rename-new-name`` str (required) New name for the playlist ========================== ==== ========== ============================ -------------- ``clear_playlist`` ~~~~~~~~~~~~~~~~~~ Delete all items from a playlist. .. code:: bash pytubekit clear_playlist --clear-name "Temp" pytubekit clear_playlist --clear-name "Temp" --no-do-delete # Dry run **Parameters:** ================ ==== ========== ============================ Parameter Type Default Description ================ ==== ========== ============================ ``--clear-name`` str (required) Name of playlist to clear ``--do-delete`` bool True Actually perform deletions ``--page-size`` int 50 Page size for API pagination ================ ==== ========== ============================ -------------- ``overflow`` ~~~~~~~~~~~~ Move videos from a source playlist to a destination playlist, respecting YouTube's 5,000-item playlist limit. .. code:: bash pytubekit overflow --source "Big Playlist" --destination "Big Playlist Overflow" pytubekit overflow --source "Big Playlist" --destination "Overflow" --no-do-delete # Dry run **Parameters:** +------------------------+------+------------+------------------------------------------+ | Parameter | Type | Default | Description | +========================+======+============+==========================================+ | ``--source`` | str | (required) | Source playlist name | +------------------------+------+------------+------------------------------------------+ | ``--destination`` | str | (required) | Destination playlist name | +------------------------+------+------------+------------------------------------------+ | ``--do-delete`` | bool | True | Actually move (set to False for dry run) | +------------------------+------+------------+------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +------------------------+------+------------+------------------------------------------+ -------------- ``add_file_to_playlist`` ~~~~~~~~~~~~~~~~~~~~~~~~ Add video IDs from a file to a playlist. .. code:: bash pytubekit add_file_to_playlist --add-file ids.txt --add-playlist "My Playlist" **Parameters:** +------------------------+------+------------+-------------------------------------------------+ | Parameter | Type | Default | Description | +========================+======+============+=================================================+ | ``--add-file`` | str | (required) | Path to text file with video IDs (one per line) | +------------------------+------+------------+-------------------------------------------------+ | ``--add-playlist`` | str | (required) | Name of playlist to add videos to | +------------------------+------+------------+-------------------------------------------------+ | ``--page-size`` | int | 50 | Page size for API pagination | +------------------------+------+------------+-------------------------------------------------+ -------------- Local Commands (Zero API Quota) ------------------------------- These commands work entirely on dump files produced by ``dump``. They make **zero YouTube API calls** and consume no quota. .. tip:: The ``find_video``, ``stats``, and ``search_playlist`` commands also support local mode via ``--local-dump-folder``. ``local_diff`` ~~~~~~~~~~~~~~ Read two paths (each can be a file or folder) and compute the set difference A−B (default) or intersection A∩B (``--local-diff-reverse``). .. code:: bash # IDs in folder A but not in folder B pytubekit local_diff --local-diff-a /dump/all --local-diff-b /dump/seen # IDs in both A and B pytubekit local_diff --local-diff-a /dump/all --local-diff-b /dump/seen --local-diff-reverse **Parameters:** ======================== ==== ========== =============================== Parameter Type Default Description ======================== ==== ========== =============================== ``--local-diff-a`` str (required) Path A (file or folder) ``--local-diff-b`` str (required) Path B (file or folder) ``--local-diff-reverse`` bool False ``False`` = A−B, ``True`` = A∩B ======================== ==== ========== =============================== -------------- ``local_dedup`` ~~~~~~~~~~~~~~~ Report intra-playlist duplicates (same ID appears more than once in a single file) and cross-playlist duplicates (same ID appears in multiple files). .. code:: bash pytubekit local_dedup pytubekit local_dedup --local-dump-folder /path/to/dump **Parameters:** ======================= ==== ======= =================== Parameter Type Default Description ======================= ==== ======= =================== ``--local-dump-folder`` str ``.`` Path to dump folder ======================= ==== ======= =================== Output lines are prefixed with ``INTRA`` (within one file) or ``CROSS`` (across files). -------------- Download -------- ``watch_later`` ~~~~~~~~~~~~~~~ Download the Watch Later playlist using yt-dlp. .. code:: bash pytubekit watch_later No additional parameters. Uses yt-dlp with ``.netrc`` authentication.