A dual-mode command-line tool for humans and AI coding agents to inspect YouTube channels, list and filter channel uploads, resolve video-to-channel ownership, and upload videos safely via the YouTube Data API v3.
- Installation
- Usage
- Authentication & Prerequisites
- Agent Skill Installation
- Development
- Publishing
- Contributing
- License
Download and verify the latest SHA-256-checked release binary into your current directory using the bundled installer script (skills/yt-cli/scripts/install.sh):
curl -sL https://raw.githubusercontent.com/ghchinoy/yt-cli/main/skills/yt-cli/scripts/install.sh | bashInstall the binary directly with Go (1.26+):
go install github.com/ghchinoy/yt-cli@latestInspect your authenticated channel or any public channel by ID:
# View your own channel's title, ID, subscribers, and view count
yt-cli channel info --mine
# Output pure JSON for scripts or AI agents
yt-cli channel info UC_x5XG1OV2P6uZZ5FSM9Ttw --jsonCommon workflows across channels and videos:
# List the 5 most recent uploads for a channel as JSON
yt-cli channel videos UC_x5XG1OV2P6uZZ5FSM9Ttw --limit 5 --json
# List your own channel's public and unlisted videos with detailed metadata
yt-cli channel videos --mine --detailed --filter public,unlisted
# Look up which channel uploaded a specific video ID
yt-cli video channel-info dQw4w9WgXcQ --json
# Validate a video upload payload without uploading (--dry-run)
yt-cli video upload ./my-video.mp4 --title "Demo Release" --description "Walkthrough" --dry-run --json| Command | Description | Key Flags |
|---|---|---|
yt-cli channel info [channel-id] |
Fetch channel title, ID, subscriber count, and total views | --mine (-m), --json |
yt-cli channel videos [channel-id] |
List uploads for a channel with optional privacy filtering | --mine (-m), --limit (-l), --detailed (-d), --filter (-f), --json |
yt-cli video channel-info <video-id> |
Resolve owning channel ID and title from a video ID (alias: info) |
--json |
yt-cli video upload <filepath> |
Upload an .mp4 video (defaults to private visibility) |
--title (-t, required), --description (-d), --dry-run, --json |
Set NO_COLOR=1 or YT_CLI_NO_TUI=1 to disable ANSI terminal styling in non-JSON human output.
- Create or select a Google Cloud project and enable the YouTube Data API v3:
gcloud services enable youtube.googleapis.com - Download an OAuth 2.0 Desktop App
client_secret.jsonfrom the Google Cloud Console and place it in~/.config/yt-cli/:Alternatively, setmkdir -p ~/.config/yt-cli cp /path/to/client_secret.json ~/.config/yt-cli/client_secret.json
YT_CLIENT_IDandYT_CLIENT_SECRETin your environment. - Run an interactive command once to complete the browser OAuth flow and cache
~/.config/yt-cli/token.json:yt-cli channel info --mine
This repository bundles an agentskills.io-compliant skill at skills/yt-cli/SKILL.md alongside root agent guidance in GEMINI.md.
Install the skill with Gemini CLI or the Open Agent Skills CLI:
# Gemini CLI
gemini skills install https://github.com/ghchinoy/yt-cli.git --path skills/yt-cli
# Open Agent Skills CLI
npx skills add ghchinoy/yt-cliPrerequisites: Go 1.26.11+ (and Node.js 22.23+ if working on the documentation site in ./site).
git clone https://github.com/ghchinoy/yt-cli.git
cd yt-cli
# Build the CLI binary
go build -o yt-cli .
# Run unit tests with the race detector
go test -p 2 -race ./...
# Run static analysis and vulnerability checks
golangci-lint run ./...
go run golang.org/x/vuln/cmd/govulncheck@latest ./...To run and build the Astro landing site in ./site:
cd site
npm install
npm run dev
ASTRO_TELEMETRY_DISABLED=1 npm run check
ASTRO_TELEMETRY_DISABLED=1 npm run buildReleases are automated via GoReleaser and GitHub Actions (.github/workflows/release.yaml). Pushing a semantic version tag builds static cross-platform archives (Darwin, Linux, and Windows on x86_64 and arm64), injects the release version into yt-cli --version, and publishes SHA-256 checksums to GitHub Releases:
git checkout main && git pull
git tag -s v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0To test a release build locally without publishing:
goreleaser release --snapshot --cleanSee docs/RELEASING.md for the full release checklist. The static site in ./site is deployed automatically to GitHub Pages via .github/workflows/deploy-site.yml.
Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change. Make sure go test -race ./... and golangci-lint run ./... pass before submitting a PR.
Licensed under the Apache License 2.0.
Disclaimer: This is not an officially supported Google product.