ytmeta

A safe, dry-run-first command-line tool for bulk-managing YouTube video metadata — titles, descriptions, comments, watermarks, and uploads.

Built for creators, channel managers, and agencies who maintain a lot of videos and are tired of editing them one by one in the Studio UI.

Why ytmeta

Bulk-editing a YouTube channel is risky: one wrong script and dozens of titles or descriptions are overwritten with no undo. ytmeta is designed around that risk.

• Dry-run by default. Every write command previews exactly what it would change and changes nothing until you add --execute.
• Uploads are private by default, so nothing goes public by accident.
• Deletes require a typed confirmation phrase, even with --execute.
• Your secrets stay local. OAuth credentials and tokens are read from your working directory (or env vars) and are never bundled or committed.

Install

npm install -g ytmeta

Then run ytmeta --help to confirm it's available. Requires Node.js 18+.

From source

git clone https://github.com/crazyathlete220-stack/ytmeta.git
cd ytmeta
npm install
npm link        # optional: makes `ytmeta` available globally

Setup (one time)

1. In the Google Cloud Console, create a project and enable the YouTube Data API v3.

2. Create an OAuth client ID of type Desktop app and download the JSON.

3. Save it as client_secret.json in the folder you run ytmeta from (or point YTMETA_CREDENTIALS at it).

4. Authenticate:

   ytmeta login

   Your browser opens, you approve access, and a token.json is saved locally.

client_secret.json and token.json are already in .gitignore. Never commit them.

Usage

Everything is a dry-run unless you pass --execute.

Update titles in bulk

ytmeta titles examples/titles.json            # preview
ytmeta titles examples/titles.json --execute  # apply

titles.json:

[
  { "id": "VIDEO_ID", "title": "New title" }
]

Update descriptions in bulk

Replace a description outright, or add a shared header/footer to many videos at once:

[
  { "id": "VIDEO_ID_1", "description": "Full replacement text" },
  { "id": "VIDEO_ID_2", "append": "\n—\nSubscribe: https://youtube.com/@you" },
  { "id": "VIDEO_ID_3", "prepend": "📣 New playlist: https://example.com\n" }
]

ytmeta descriptions examples/descriptions.json --execute

Post comments

ytmeta comments examples/comments.json --execute

The API can't pin comments, so ytmeta posts them and prints the video URLs for you to pin in Studio.

Set a channel watermark

ytmeta watermark logo.png --channel UCxxxxxxxxxxxxxxxx --execute

Upload a video

ytmeta upload ~/Movies/clip.mp4 --title "My video" --tags "a,b,c"            # dry-run
ytmeta upload ~/Movies/clip.mp4 --title "My video" --privacy unlisted --execute

Delete videos (irreversible)

ytmeta delete VIDEO_ID_1 VIDEO_ID_2            # dry-run
ytmeta delete VIDEO_ID_1 VIDEO_ID_2 --execute  # prompts for a confirmation phrase

Command reference

| Command | What it does | Write API | |---------|--------------|-----------| | login | OAuth authentication | — | | upload <file> | Upload a video (private by default) | videos.insert | | titles <file> | Bulk title update | videos.update | | descriptions <file> | Bulk description update / append / prepend | videos.update | | comments <file> | Post comments | commentThreads.insert | | watermark <image> | Set channel watermark | watermarks.set | | delete <ids...> | Delete videos | videos.delete |

Configuration

| Env var | Default | Purpose | |---------|---------|---------| | YTMETA_CREDENTIALS | ./client_secret.json | OAuth client secret path | | YTMETA_TOKEN | ./token.json | saved token path | | YTMETA_PORT | 4796 | local port for the login callback |

Notes & limits

• Subject to the YouTube Data API quota. Bulk writes cost quota per call; ytmeta adds small delays between calls.
• Comment pinning is not available via the API — pin manually in Studio.
• You can only modify videos on channels your authenticated account owns.

License

MIT