ytcc(1)

📦
version 2.6.1 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 ytcc — the manual, bestie edition 🌸

okay so you're reading the ytcc(1) manual page and honestly? you're about to have a great time. this is the whole thing, every flag, every option, zero skips, just with me hyping you through it. 💖

✨ NAME ✨

ytcc — Command line tool to keep track of your favorite playlists on YouTube and many other places

like. it tracks your playlists. that's the whole vibe. 👑

🦋 SYNOPSIS 🦋

ytcc [OPTIONS...] COMMAND [ARGS...]

you give it options, you give it a command, you maybe give it args. slay. ✨

💅 DESCRIPTION 💅

Ytcc — the (not only) YouTube channel checker.

Ytcc "subscribes" to playlists (supported by yt-dlp or youtube-dl) and tracks new videos published to those playlists.

and yes it says "subscribes" in quotes because it's not literally subscribing, it's just keeping an eye on them. stalker-ish but make it productive. 🙈

To show the detailed help of a COMMAND run ytcc COMMAND --help.

ngl bestie, every single command has its own --help and you should absolutely use it. this page is the whole menu, that's the à la carte. 🍓

🎀 OPTIONS 🎀

  • -c, --conf FILE — Override configuration file. (yes, your config file, the one you thought was untouchable. this one wins.)
  • -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. (short and sweet, iconic behaviour honestly)
  • --help — Show help and exit.
lowkey important: json output is usually not filtered by the --attribute options of commands. that's just how it is, no cap.

🌈 COMMANDS 🌈

💖 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! fr fr, be careful. 😭
  • --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.

so like… if a video lives on two playlists and you only unsubscribe from one, it survives. it's giving "you can't get rid of me that easily". 🦋

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.

just the metadata bestie. it's window shopping, not buying. 👀

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

this one is the moment. the pipeline queen. 💅

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.

main character energy fr. it's giving full terminal glow-up. ✨

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.
the symlink thing is so clever?? one download, many homes. it's giving share the love. 🫶

😭 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.

bestie. bestie listen to me. CANNOT. BE. UNDONE. do not vibe-check this command carelessly. 💀

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!

pls pls pls include it. the devs are literally begging and they deserve it. 🥺

OPTIONS:

  • --help — Show command help and exit.

⭐ SEE ALSO ⭐

mpv(1), yt-dlp(1), youtube-dl(1)

💖 Project homepage

https://github.com/woefe/ytcc

🎀 Bug Tracker

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

and that's the whole thing, bestie. you ate. periodt. 💅✨

this has been ytcc manual, version 2.6.1, dated Oct 2022 — go forth and subscribe to playlists responsibly 🫶🌸

📦 where this page comes from