📦 Installation

Global Install (dev mode)

git clone https://github.com/mrhansamala/youtube-toolkit.git
cd youtube-toolkit
npm install
npm link   # makes `youtube-toolkit` available globally

Uninstall:

npm unlink -g @mrhansamala/youtube-toolkit

⚙️ Setup API Keys

Go to Google Cloud Console .

Enable these APIs:

✅ YouTube Data API v3

✅ YouTube Analytics API

✅ YouTube Reporting API

Create OAuth2 credentials.

💻 Usage

🔎 1. Search Videos

@mrhansamala/youtube-toolkit --mode=search --q="cricket news" --max=5

✅ Sample Result

{
  "query": "cricket news",
  "mode": "api",
  "count": 5,
  "results": [
    {
       "videoId": "1ZYbU82GVz4",
      "url": "https://www.youtube.com/watch?v=1ZYbU82GVz4",
      "title": "Flying: Relaxing Sleep Music for Meditation, Stress Relief & Relaxation by Peder B. Helland",
      "channelId": "UCjzHeG1KWoonmf9d5KBvSiw",
      "channelTitle": "Soothing Relaxation",
      "publishedAt": "2016-07-03T17:09:48Z",
      "description": "Relaxing sleep music for deep sleeping and stress relief. Fall asleep to beautiful nature videos and use the relaxing music ...",
    }
  ]
}

📝 Full Result

 {
      "source": "api",
      "videoId": "1ZYbU82GVz4",
      "url": "https://www.youtube.com/watch?v=1ZYbU82GVz4",
      "title": "Flying: Relaxing Sleep Music for Meditation, Stress Relief & Relaxation by Peder B. Helland",
      "channelId": "UCjzHeG1KWoonmf9d5KBvSiw",
      "channelTitle": "Soothing Relaxation",
      "publishedAt": "2016-07-03T17:09:48Z",
      "description": "Relaxing sleep music for deep sleeping and stress relief. Fall asleep to beautiful nature videos and use the relaxing music ...",
      "thumbnails": {
        "default": {
          "url": "https://i.ytimg.com/vi/1ZYbU82GVz4/default.jpg",
          "width": 120,
          "height": 90
        },
        "medium": {
          "url": "https://i.ytimg.com/vi/1ZYbU82GVz4/mqdefault.jpg",
          "width": 320,
          "height": 180
        },
        "high": {
          "url": "https://i.ytimg.com/vi/1ZYbU82GVz4/hqdefault.jpg",
          "width": 480,
          "height": 360
        }
      }
    }
  ]
}

📊 2. Fetch Analytics

@mrhansamala/youtube-toolkit --mode=analytics --startDate=2025-08-01 --endDate=2025-09-01

✅ Sample Result

{
  "rows": [
    ["2025-08-01", "1000", "150", "25"],
    ["2025-08-02", "1200", "180", "40"]
  ],
  "columnHeaders": [
    { "name": "day" },
    { "name": "views" },
    { "name": "estimatedMinutesWatched" },
    { "name": "subscribersGained" }
  ]
}

📝 3. Download Reporting Jobs

@mrhansamala/youtube-toolkit --mode=reporting

✅ Sample Result

{
  "jobs": [
    {
      "id": "job-123456",
      "reportTypeId": "channel_basic_a2",
      "name": "Channel Basic Report"
    }
  ]
}

🛠️ Advanced Usage

Enable Debug Mode

@mrhansamala/youtube-toolkit --mode=search --q="sri lanka news" --debug

Pipe Results into jq

@mrhansamala/youtube-toolkit --mode=search --q="music mix" --max=3 | jq '.results[].title'

Export Analytics to CSV

@mrhansamala/youtube-toolkit --mode=analytics --startDate=2025-08-01 --endDate=2025-09-01 > analytics.json
jq -r '.rows[] | @csv' analytics.json > analytics.csv

📂 Project Structure

@mrhansamala/youtube-toolkit/
 ├─ index.js          # Main CLI entry
 ├─ package.json      # NPM config
 ├─ README.md         # Docs
 └─ token.json        # Auto-created after OAuth login

⚠️ Notes

API quota applies (10,000 units/day default).

Scraper mode (--mode=scrape) is fragile – may break any time.

Recommended: always use API mode.

👨‍💻 Owner

Made with ❤️ by mrhansamala MIT License © 2025