ytee

A minimal CLI for uploading videos to YouTube — single files or entire directories — powered by the YouTube Data API v3.

pip install --upgrade ytee

Quickstart

ytee init → ytee set-creds → ytee upload

These three commands are all you need. init must be run before anything else.

Installation

pip install ytee

Requires Python 3.9+.

Setup

1. Get Google API credentials

Before using ytee, you need a Google Cloud project with the YouTube Data API v3 enabled:

1. Go to the Google Cloud Console.
2. Enable the YouTube Data API v3.
3. Create OAuth 2.0 credentials for a Desktop application.
4. Download the credentials as a JSON file (e.g. client_secret.json).

CLI Commands

ytee init — Run this first

Copies your Google OAuth credentials into ~/.ytee/.google_secrets/ so ytee can find them.

ytee init --secret-path /path/to/client_secret.json

⚠️ This must be run at least once before any other command will work.

ytee migrate — Migrate from v0.1.0

If you used ytee version v0.1.0, your credentials were stored under ~/.secrets/. Newer versions store them in ~/.ytee/.google_secrets/.

Run this once to move your existing credentials to the new location:

ytee migrate

Only needed if you previously ran ytee init on v0.1.0.

ytee set-creds — Authenticate with Google

Opens a browser window for Google OAuth authorization and saves the access token to ~/.ytee/.google_secrets/token.json.

ytee set-creds

Run this after init. If your credentials are still valid they are reused automatically — you don't need to re-run this every time. If your token has expired, ytee will automatically open the browser to re-authenticate.

ytee verify-creds — Check credential status

Checks whether client_secret.json and token.json are present in ~/.ytee/.google_secrets/.

ytee verify-creds

ytee upload — Upload a video or directory

Upload a single video:

ytee upload --path video.mp4 --name "My Video Title" --desc "My description"

Upload all videos in a directory:

ytee upload --path ./videos --name "Episode - " --desc "My description"

When a directory path is given, ytee automatically detects it and uploads every file inside. Each filename (without extension) is appended to the --name prefix to form the video title. For example, if the directory contains part1.mp4, the title becomes Episode - part1.

Supported formats: .mp4, .mov, .avi, .wmv, .mkv, .webm, .m4v, .mpeg, .mpg, .flv

After each successful upload, ytee saves a log entry to ~/.ytee/.uploads/uploaded.json.

Uploads show a live progress table displaying upload speed, file size, time elapsed, and time remaining.

ytee show-uploads — View upload history

ytee show-uploads

Prints the contents of ~/.ytee/.uploads/uploaded.json, showing the file path, video title, and YouTube video ID of every past upload.

Full Example Walkthrough

# Step 1 — point ytee to your Google credentials (once)
ytee init --secret-path ~/Downloads/client_secret.json

# Step 2 — authenticate with Google (once, or when token expires)
ytee set-creds

# Step 3 — check credentials are in place (optional)
ytee verify-creds

# Step 4a — upload a single video
ytee upload --path ~/videos/intro.mp4 --name "Introduction" --desc "Welcome to my channel"

# Step 4b — or upload a whole folder
ytee upload --path ~/videos --name "Lecture - " --desc "Course upload"

# Step 5 — view upload history
ytee show-uploads

Error handling & retries

ytee handles common upload failures gracefully:

• Token expired — detected before and during upload, prompts you to run ytee set-creds
• Quota exceeded — YouTube's daily 10,000 unit limit (each upload costs ~1,600 units). ytee reports this clearly when hit. Quota resets at midnight Pacific Time.
• Network errors — timeouts, SSL errors, and connection drops are retried automatically with exponential backoff, up to 10 retries
• Server errors — YouTube 5xx errors are retried up to 5 times
• Unsupported file types — filtered out before upload with a clear message

Notes

• Videos are uploaded as unlisted by default. Use --privacy public or --privacy private to change this.
• Credentials are stored in ~/.ytee/.google_secrets/ (client_secret.json and token.json).
• Upload history is stored in ~/.ytee/.uploads/uploaded.json.
• Directory uploads process files sequentially with a short delay between each upload.

Dependencies