YouTube Creator CLI

A command-line tool for managing YouTube channels, videos, and content. Upload videos, manage metadata, set thumbnails, and interact with the YouTube Data API v3.

🚨 Important: User-Provided Credentials

This is an open-source tool that requires you to provide your own Google OAuth credentials. No credentials are included in this repository.

Prerequisites

Node.js 18 or higher
A Google account
Git

Installation

Option 1: Install from npm (Recommended)

Install globally from npm:

npm install -g youtube-creator-cli

Option 2: Install from Source

Clone the repository and build locally:

git clone https://github.com/hcassar93/youtube-cli.git
cd youtube-cli
npm install
npm run build
npm link  # Install globally

Once installed, you can use youtube-creator-cli from anywhere:

youtube-creator-cli --version
youtube-creator-cli setup
youtube-creator-cli auth
youtube-creator-cli upload video.mp4 --title "My Video"

Getting Started

Step 1: Get OAuth Credentials from Google

Create a Google Cloud Project
- Go to: https://console.cloud.google.com/
- Create a new project or select existing
Enable YouTube Data API v3
- Navigate to: https://console.cloud.google.com/apis/library/youtube.googleapis.com
- Click "Enable"
Configure OAuth Consent Screen ⚠️ IMPORTANT
- Go to: https://console.cloud.google.com/apis/credentials/consent
- Choose "External" user type
- Fill in app name and your email
- Add these scopes:
  - https://www.googleapis.com/auth/youtube
  - https://www.googleapis.com/auth/youtube.force-ssl
  - https://www.googleapis.com/auth/youtube.upload
- CRITICAL: Add your Google email as a test user (without this, auth will fail with "Access blocked")
Create OAuth 2.0 Client ID
- Go to: https://console.cloud.google.com/apis/credentials
- Click "Create Credentials" → "OAuth 2.0 Client ID"
- Application type: "Desktop app"
- Add authorized redirect URI: http://localhost:3000/oauth2callback
- Copy the Client ID and Client Secret

Step 2: Configure the CLI

Run the interactive setup:

npm run dev -- setup

Or non-interactive:

npm run dev -- setup \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --default-privacy private \
  --port 3000 \
  --non-interactive

Step 3: Authenticate

npm run dev -- auth

A browser window will open. Sign in with your Google account and grant permissions.

Usage

Upload a Video

npm run dev -- upload video.mp4 \
  --title "My Amazing Video" \
  --description "Video description here" \
  --privacy private \
  --tags "tag1,tag2,tag3"

List Your Videos

npm run dev -- videos --limit 20
npm run dev -- videos --status private
npm run dev -- videos --format json

Update Video Metadata

npm run dev -- update VIDEO_ID \
  --title "New Title" \
  --description "Updated description" \
  --privacy public

Set Thumbnail

npm run dev -- thumbnail VIDEO_ID thumbnail.jpg

List Channels

npm run dev -- channels

Get Video Stats

npm run dev -- stats VIDEO_ID

Manage Playlists

# List playlists
npm run dev -- playlists

# Create playlist
npm run dev -- playlist-create \
  --title "My Playlist" \
  --privacy private

# Add video to playlist
npm run dev -- playlist-add PLAYLIST_ID VIDEO_ID

Comments

# List comments
npm run dev -- comments VIDEO_ID --limit 50

# Post comment
npm run dev -- comment VIDEO_ID "Great video!"

All Commands

If using npm link (global), replace npm run dev -- with youtube-creator-cli:

# Without npm link
npm run dev -- setup              # Interactive setup wizard
npm run dev -- config show        # View configuration
npm run dev -- config set KEY VAL # Set config value
npm run dev -- reset              # Remove all config
npm run dev -- auth               # Authenticate
npm run dev -- logout             # Remove tokens
npm run dev -- channels           # List channels
npm run dev -- videos             # List videos
npm run dev -- upload FILE        # Upload video
npm run dev -- update VIDEO_ID    # Update video
npm run dev -- delete VIDEO_ID    # Delete video
npm run dev -- stats VIDEO_ID     # Get video stats
npm run dev -- thumbnail VIDEO IMAGE # Set thumbnail
npm run dev -- playlists          # List playlists
npm run dev -- playlist-create    # Create playlist
npm run dev -- playlist-add       # Add video to playlist
npm run dev -- comments VIDEO_ID  # List comments
npm run dev -- comment VIDEO TEXT # Post comment

# With npm link (after running 'npm link')
youtube-creator-cli setup
youtube-creator-cli config show
youtube-creator-cli auth
# ... etc

Add --help to any command for more options.

Common Options

--privacy <privacy> - private, unlisted, or public
--format <format> - Output format: table (default) or json
--limit <number> - Limit results
--tags <tags> - Comma-separated tags
--category <id> - YouTube category ID
--port <port> - OAuth callback port (default: 3000)

Configuration

Configuration is stored at: ~/.youtube-creator-cli/config.json

The file has restricted permissions (0600) and includes:

OAuth credentials (client ID, client secret)
Access and refresh tokens
Default settings (privacy, category, output format)

Never commit this file to version control.

Troubleshooting

"Access blocked: This app's request is invalid"

Problem: You weren't added as a test user in the OAuth consent screen.

Solution:

Go to: https://console.cloud.google.com/apis/credentials/consent
Click "Test Users"
Add your Google email address
Try npm run dev -- auth again

"Configuration not found"

Run: npm run dev -- setup

"Invalid client credentials"

Your OAuth credentials may be incorrect. Run setup again and double-check your Client ID and Secret.

"Port already in use"

npm run dev -- auth --port 3001

Or update config: npm run dev -- config set oauth.port 3001

"Token expired"

The CLI auto-refreshes tokens, but if that fails:

npm run dev -- logout
npm run dev -- auth

"Upload quota exceeded"

YouTube has daily upload quotas. Check at: https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas

Development

# Run in dev mode (no build needed, changes reflected immediately)
npm run dev -- COMMAND

# Build TypeScript
npm run build

# Link globally for testing (after building)
npm link

# Now test as if it's installed
youtube-creator-cli --help

# Make changes, rebuild, and test again
npm run build
youtube-creator-cli COMMAND

# Unlink when done
npm unlink -g youtube-creator-cli

Security

Credentials are stored locally only
Config file has restricted permissions (owner read/write only)
Never commit config files to git
No intermediary servers - direct API calls to YouTube
OAuth tokens automatically refresh

API Limits

YouTube Data API v3 has quota limits:

Default: 10,000 units per day
Upload: ~1600 units per video
Check usage: https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas

License

MIT License - see LICENSE file for details.

Links

YouTube Data API v3: https://developers.google.com/youtube/v3
Google Cloud Console: https://console.cloud.google.com/

Note: This tool is not affiliated with or endorsed by Google or YouTube.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
compliance-skill.md		compliance-skill.md
package-lock.json		package-lock.json
package.json		package.json
skill.md		skill.md
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

YouTube Creator CLI

🚨 Important: User-Provided Credentials

Prerequisites

Installation

Option 1: Install from npm (Recommended)

Option 2: Install from Source

Getting Started

Step 1: Get OAuth Credentials from Google

Step 2: Configure the CLI

Step 3: Authenticate

Usage

Upload a Video

List Your Videos

Update Video Metadata

Set Thumbnail

List Channels

Get Video Stats

Manage Playlists

Comments

All Commands

Common Options

YouTube Category IDs

Configuration

Troubleshooting

"Access blocked: This app's request is invalid"

"Configuration not found"

"Invalid client credentials"

"Port already in use"

"Token expired"

"Upload quota exceeded"

Development

Security

API Limits

License

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages