-c, --conf FILE¶

Override configuration file.

-l, --loglevel [critical|info|debug]¶

Set the log level. Overrides the log level configured in the config file. [default: info]

-o, --output [json|table|xsv|rss|plain]¶

Set output format. `json` prints in JSON format, which is usually not filtered by --attribute options of commands. `table` prints a human readable table. `xsv` prints x-separated values, where x can be set with the -s option. `rss` prints a RSS 2.0 feed of videos. `plain` prints in a human readable text format. [default: table]

-s, --separator TEXT¶

Set the delimiter used in XSV format. [default: ,]

-t, --truncate TRUNCATE¶

Truncate the table output. 'max' truncates to terminal width, 'no' disables truncating, an integer N truncates to length N. [default: max]

--version¶

Show the version and exit.

--help¶

Show help and exit.

subscribe [OPTIONS] NAME URL¶

Subscribe to a playlist.

The NAME argument is the name used to refer to the playlist. The URL argument is the URL to a
playlist that is supported by yt-dlp or youtube-dl.

OPTIONS:

--reverse Check the playlist in reverse order. This should be used for playlists where the latest videos are added to the end of the playlist. WARNING: Using this option on large playlists slows down updating!

--help Show command help and exit.

unsubscribe [OPTIONS] NAMES...¶

Unsubscribe from a playlist.

Unsubscribes from the playlist identified by NAMES. Videos that are on any of the given
playlists will be removed from the database as well, unless the videos are on at least one
playlist not given in NAMES.

OPTIONS:

--yes Confirm the action without prompting.

--help Show command help and exit.

rename [OPTIONS] OLD NEW¶

Rename a playlist.

Renames the playlist OLD to NEW.

OPTIONS:

--help Show command help and exit.

reverse [OPTIONS] [PLAYLISTS]...¶

Toggle the update behavior of playlists.

Playlists updated in reverse might lead to slow updates with the `update` command.

OPTIONS:

--help Show command help and exit.

subscriptions [OPTIONS]¶

List all subscriptions.

OPTIONS:

-a, --attributes COMMA_SEPARATED_VALUES Attributes of the playlist to be included in the output. Some of [name, url, tags, reverse].

--help Show command help and exit.

tag [OPTIONS] NAME [TAGS]...¶

Set tags of a playlist.

Sets the TAGS associated with the playlist called NAME. If no tags are given, all tags are
removed from the given playlist.

OPTIONS:

--help Show command help and exit.

update [OPTIONS]¶

Check if new videos are available.

Downloads metadata of new videos (if any) without playing or downloading the videos.

OPTIONS:

-f, --max-fail INTEGER Number of failed updates before a video is not checked for updates any more.

-b, --max-backlog INTEGER Number of videos in a playlist that are checked for updates.

--help Show command help and exit.

list [OPTIONS]¶

List videos.

Lists videos that match the given filter options. By default, all unwatched videos are listed.

OPTIONS:

-a, --attributes COMMA_SEPARATED_VALUES Attributes of videos to be included in the output. Some of [id, url, title, description, publish_date, watched, duration, thumbnail_url, extractor_hash, playlists].

-c, --tags COMMA_SEPARATED_VALUES Listed videos must be tagged with one of the given tags.

-s, --since [%Y-%m-%d] Listed videos must be published after the given date.

-t, --till [%Y-%m-%d] Listed videos must be published before the given date.

-p, --playlists COMMA_SEPARATED_VALUES Listed videos must be in on of the given playlists.

-i, --ids COMMA_SEPARATED_VALUES Listed videos must have the given IDs.

-w, --watched Only watched videos are listed.

-u, --unwatched Only unwatched videos are listed.

-o, --order-by <ATTRIBUTE DIRECTION>... Set the column and direction to sort listed videos. ATTRIBUTE is one of [id, url, title, description, publish_date, watched, duration, thumbnail_url, extractor_hash, playlists]. Direction is one of [asc, desc].

--help Show command help and exit.

ls [OPTIONS]¶

List IDs of unwatched videos in XSV format.

Basically an alias for `ytcc --output xsv list --attributes id`. This alias can be useful for
piping into the download, play, and mark commands. E.g: `ytcc ls | ytcc watch`

OPTIONS:

-c, --tags COMMA_SEPARATED_VALUES Listed videos must be tagged with one of the given tags.

-s, --since [%Y-%m-%d] Listed videos must be published after the given date.

-t, --till [%Y-%m-%d] Listed videos must be published before the given date.

-p, --playlists COMMA_SEPARATED_VALUES Listed videos must be in on of the given playlists.

-i, --ids COMMA_SEPARATED_VALUES Listed videos must have the given IDs.

-w, --watched Only watched videos are listed.

-u, --unwatched Only unwatched videos are listed.

-o, --order-by <ATTRIBUTE DIRECTION>... Set the column and direction to sort listed videos. ATTRIBUTE is one of [id, url, title, description, publish_date, watched, duration, thumbnail_url, extractor_hash, playlists]. Direction is one of [asc, desc].

--help Show command help and exit.

tui [OPTIONS]¶

Start an interactive terminal user interface.

OPTIONS:

-c, --tags COMMA_SEPARATED_VALUES Listed videos must be tagged with one of the given tags.

-s, --since [%Y-%m-%d] Listed videos must be published after the given date.

-t, --till [%Y-%m-%d] Listed videos must be published before the given date.

-p, --playlists COMMA_SEPARATED_VALUES Listed videos must be in on of the given playlists.

-i, --ids COMMA_SEPARATED_VALUES Listed videos must have the given IDs.

-w, --watched Only watched videos are listed.

-u, --unwatched Only unwatched videos are listed.

-o, --order-by <ATTRIBUTE DIRECTION>... Set the column and direction to sort listed videos. ATTRIBUTE is one of [id, url, title, description, publish_date, watched, duration, thumbnail_url, extractor_hash, playlists]. Direction is one of [asc, desc].

--help Show command help and exit.

play [OPTIONS] [IDS]...¶

Play videos.

Plays the videos identified by the given video IDs. If no IDs are given, ytcc tries to read IDs
from stdin. If no IDs are given and no IDs were read from stdin, all unwatched videos are
played.

OPTIONS:

-a, --audio-only Play only the audio track.

-i, --no-meta Don't print video metadata and description.

-m, --no-mark Don't mark the video as watched after playing it.

--help Show command help and exit.

mark [OPTIONS] [IDS]...¶

Mark videos as watched.

Marks videos as watched without playing or downloading them. If no IDs are given, ytcc tries to
read IDs from stdin. If no IDs are given and no IDs were read from stdin, no videos are marked
as watched.

OPTIONS:

--help Show command help and exit.

unmark [OPTIONS] [IDS]...¶

Mark videos as unwatched.

Marks videos as unwatched. If no IDs are given, ytcc tries to read IDs from stdin. If no IDs
are given and no IDs were read from stdin, no videos are marked as watched.

OPTIONS:

--help Show command help and exit.

download [OPTIONS] [IDS]...¶

Download videos.

Downloads the videos identified by the given video IDs. If no IDs are given, ytcc tries to read
IDs from stdin. If no IDs are given and no IDs were read from stdin, all unwatched videos are
downloaded.

OPTIONS:

-p, --path DIRECTORY Set the download directory.

-a, --audio-only Download only the audio track.

-m, --no-mark Don't mark the video as watched after downloading it.

--subdirs / --no-subdirs Creates subdirectories per playlist. If a video is on multiple playlists, it gets downloaded only once and symlinked to the other subdirectories.

--help Show command help and exit.

cleanup [OPTIONS]¶

Remove all watched videos from the database.

WARNING!!! This removes all metadata of watched, marked as watched, and downloaded videos from
ytcc's database. This cannot be undone! In most cases you won't need this command, but it is
useful to keep the database size small.

OPTIONS:

-k, --keep INTEGER Number of videos to keep. Defaults to the max_update_backlog setting.

--yes Confirm the action without prompting.

--help Show command help and exit.

import [OPTIONS] FILE¶

Import YouTube subscriptions from an OPML or CSV file.

The CSV file must have three columns in following order: Channel ID, Channel URL, Channel name.

You can export your YouTube subscriptions at https://takeout.google.com. In the takeout you
find a CSV file with your subscriptions. To speed up the takeout export only your
subscriptions, not your videos, comments, etc.

The OPML export was available on YouTube some time ago and old versions of ytcc were also able
to export subscriptions in the OPML format.

OPTIONS:

-f, --format [opml|csv] Format of the file to import. [default: csv]

--help Show command help and exit.

bug-report [OPTIONS]¶

Show debug information for bug reports.

Shows versions of dependencies and configuration relevant for any bug report. Please include
the output of this command when filing a new bug report!

OPTIONS:

--help Show command help and exit.

Project homepage¶

https://github.com/woefe/ytcc

Bug Tracker¶

https://github.com/woefe/ytcc/issues