GopherUpload - CLI YouTube Video Uploader

What is GopherUpload?

GopherUpload is a lightweight command-line tool that uploads videos to YouTube using the YouTube Data API v3.

📤 Video Uploads

Upload videos with custom metadata directly from your terminal.

📝 Custom Metadata

Set title, description, and tags from a metadata.json file.

🖼️ Custom Thumbnails

Automatically upload thumbnail.png with your video.

📅 Scheduled Publishing

Schedule videos to publish at a specific date and time.

🏷️ Hashtags Support

Automatically append hashtags to your video descriptions.

⚡ Lightweight & Fast

Built with Go for maximum performance and minimal overhead.

Quick Start

Get started in seconds

# 1. Authenticate with Google
gopherupload login

# 2. Upload a video
gopherupload upload "outputs/My Video Folder"

Installation

Prerequisites

Go 1.21 or later
Google OAuth2 credentials for YouTube Data API v3

Build from Source

# Clone the repository
git clone https://github.com/yourusername/gopherupload.git
cd gopherupload

# Get dependencies
go mod tidy

# Build the application
go build -o gopherupload

# (Optional) Move to PATH
# Windows: move gopherupload.exe to a directory in your PATH
# macOS/Linux: sudo mv gopherupload /usr/local/bin/

Configuration

1. Google OAuth2 Credentials

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the YouTube Data API v3 from the API Library
Go to "Credentials" → "Create Credentials" → "OAuth client ID"
Select "Desktop app" as the application type
Download the credentials JSON file
Save it as client_secrets.json in the GopherUpload directory

2. Application Config (Optional)

Create a config.json file to set upload defaults:

{
  "upload_defaults": {
    "default_privacy": "public",
    "default_category": "22",
    "default_description": "Uploaded with GopherUpload",
    "default_tags": ["video", "upload"]
  }
}

Category IDs

ID	Category
`1`	Film & Animation
`2`	Autos & Vehicles
`10`	Music
`15`	Pets & Animals
`17`	Sports
`20`	Gaming
`22`	People & Blogs (default)
`23`	Comedy
`24`	Entertainment
`25`	News & Politics
`26`	Howto & Style
`27`	Education
`28`	Science & Technology

Usage

Authentication

Before uploading, authenticate with your Google account:

gopherupload login

Note: The token is valid for ~1 hour. Run login again when it expires.

Upload a Video

gopherupload upload <directory>

The directory should contain:

One .mp4 file (required) - the video to upload
metadata.json (optional) - video metadata
thumbnail.png (optional) - custom thumbnail

Directory Structure Example

outputs/My Video/
├── My Video.mp4        # Required: video file
├── metadata.json       # Optional: metadata
└── thumbnail.png       # Optional: thumbnail

metadata.json Format

{
  "youtube": {
    "title": "My Awesome Video",
    "description": "This is a great video about...",
    "tags": ["tutorial", "coding", "golang"],
    "hashtags": ["#programming", "#tech"],
    "schedule": {
      "publish_date": "2025-12-31",
      "publish_time": "10:00"
    }
  }
}

Field	Type	Description
`title`	string	Video title (uses filename if empty)
`description`	string	Video description
`tags`	array	Search tags (no # symbol)
`hashtags`	array	Hashtags (with # symbol, appended to description)
`schedule.publish_date`	string	Publish date (YYYY-MM-DD)
`schedule.publish_time`	string	Publish time (HH:MM, system timezone)

Commands

gopherupload login Authenticate with Google

gopherupload upload <directory> Upload video from directory

gopherupload help Show detailed help

Troubleshooting

"Token not found" error

Run gopherupload login to authenticate.

"Multiple .mp4 files found" error

The upload directory must contain exactly one .mp4 file.

"Scheduled time is in the past" warning

The video will upload as public immediately instead of scheduled.

Upload quota exceeded

YouTube API has daily quota limits. See YouTube API Quotas for details.