← Wiki
2026-11-07 concept youtubeclioauthapivideoagents

YouTube channels from the terminal

Short version

A single Python script talking to the YouTube Data API v3 covers upload, subtitles, thumbnail, playlist, publish, privacy and stats. Auth is a Desktop OAuth client plus one token file per channel (--account NAME). Budget: 10,000 quota units a day, an upload costs about 1600, so 5 to 6 uploads a day. Uploads from an unaudited API project arrive private. Publish the OAuth app (Testing to In production) or the token dies every 7 days.

For a coding agent

Give your agent this page, or install the skill that holds the same steps in agent form:

# any agent (Claude Code, Cursor, Codex, Gemini CLI, ...)
npx skills add fortunto2/solo-factory --skill solo-youtube-channel -g
# or Claude Code, the whole solo plugin
claude plugin marketplace add https://github.com/fortunto2/solo-factory
claude plugin install solo@solo --scope user

Skill source: https://github.com/fortunto2/solo-factory/tree/main/skills/youtube-channel. The skill carries the rules (gates before upload, quota, private-first, Shorts linking, analytics); the agent writes the upload script from it with google-api-python-client. Only the Console clicks and the channel chooser in the browser need your hands.

Steps

1. OAuth client (browser, once)

  1. Google Cloud Console, create a project (my-project).
  2. APIs and Services, Library: enable YouTube Data API v3 (and YouTube Analytics API if you want stats).
  3. Google Auth Platform, Branding: fill it (see key lesson below).
  4. Clients, Create client, type Desktop app, Download JSON.
  5. Save it as ~/.config/my-yt/client_secret.json.

The same project can also hold the Gmail client, see gmail-cli-several-mailboxes-gws.

2. Script

My script lives in a private repo, so treat the commands below as the shape to build, not a download: every one of them is a few lines over google-api-python-client, and a coding agent writes the file from this page in one pass.

The script is a single PEP 723 file (dependencies google-api-python-client, google-auth-oauthlib), run with uv run, so there is nothing to install. Scopes: youtube.upload, youtube, youtube.force-ssl. The last one is needed for subtitle tracks, youtube.upload alone cannot add them.

3. Auth, one token per channel

uv run yt_upload.py auth                    # default channel -> token.json
uv run yt_upload.py --account second auth   # another channel -> token-second.json
uv run yt_upload.py channel                 # who is authorised

The browser asks which account to use and then which channel. For a brand channel, pick it in that chooser, otherwise the token belongs to your personal channel. --account NAME (or env YT_ACCOUNT) selects the token file for every later command. Check channel after auth.

4. Commands

uv run yt_upload.py upload film.mp4 --title "Title" --description-file d.md \
    --tags "a,b" --privacy private --playlist "My playlist" --thumb thumb.jpg \
    --subs-ru film.ru.srt --subs-en film.en.srt --recorded 2026-10-12
uv run yt_upload.py publish VIDEO_ID                  # private -> public
uv run yt_upload.py privacy unlisted ID1 ID2 ...      # bulk
uv run yt_upload.py captions VIDEO_ID --subs-en x.en.srt
uv run yt_upload.py describe VIDEO_ID --description-file d.md --thumb new.jpg
uv run yt_upload.py list --limit 60
uv run yt_upload.py stats --days 30

Large files go up in resumable chunks, so a dropped connection continues rather than restarts. --thumb takes a jpg or a second of the film. --playlist finds the playlist by name or creates it. Titles are capped at 100 characters (invalidTitle above that). A video id that starts with - needs -- before it.

5. Quota

6. Uploads land private

A video uploaded through an API project that has not passed Google’s audit is locked to private, whatever --privacy says. Publish separately: publish ID (50 units) or flip it in Studio. For a family archive this is the wanted mode.

Key lesson: Testing status kills the token in 7 days

Measured 7 Nov 2026: an OAuth app left in Testing publishing status issues refresh tokens that expire after 7 days, and the script fails with invalid_grant once a week. The YouTube token and the Gmail token both died this way.

Fix:

  1. Google Cloud Console, Google Auth Platform, Audience, Publish app (Testing to In production).
  2. The button stays disabled with “To publish your app, you must complete your configuration on the Branding page” until Branding has:
    • an app name without Google trademarks (a name with “Gmail” in it was renamed),
    • an application home page,
    • a privacy policy link,
    • that domain under Authorised domains.
  3. Do not upload a logo. A logo forces Google verification.
  4. After publishing, run auth again once. The old token is dead, the new one does not expire weekly.

Personal use stays unverified: the consent screen shows “Google hasn’t verified this app” (Advanced, Go to app), user cap 100. Afterwards invalid_grant means a revoked grant or a changed password, not the calendar.

Pitfalls

Numbers

Related

Learned from

Session 2026-11-07 (OAuth Testing to Production), plus months of running yt_upload.py on two channels.

Related