youtube-search

Search YouTube and return structured video results as JSON.

Usage

Run the search script with a query:

node .agents/skills/youtube-search/scripts/search.mjs "your search query"

Options

| Argument | Description | Default | |----------|-------------|---------| | 1st positional | Search query (required) | — | | --max-results=N | Maximum number of results to return | 10 | | --upload-date=PERIOD | Filter by upload date: hour, today, week, month, year | no filter | | --duration=LENGTH | Filter by duration: short (<4 min), medium (4–20 min), long (>20 min) | no filter |

Examples

# Basic search
node .agents/skills/youtube-search/scripts/search.mjs "typescript tutorial"

# Limit results
node .agents/skills/youtube-search/scripts/search.mjs "bun runtime" --max-results=5

# Filter by upload date
node .agents/skills/youtube-search/scripts/search.mjs "claude code" --upload-date=month

# Combine filters
node .agents/skills/youtube-search/scripts/search.mjs "react tutorial" --max-results=5 --upload-date=week --duration=long

Output Format

The script outputs a JSON array to stdout. Each element has:

[
  {
    "videoId": "dQw4w9WgXcQ",
    "title": "Video title",
    "channel": {
      "name": "Channel Name",
      "id": "UCxxxxxx",
      "url": "https://www.youtube.com/channel/UCxxxxxx"
    },
    "duration": "3:32",
    "viewCount": "1,234,567 views",
    "publishedTime": "2 days ago",
    "publishedDate": "2026-02-18",
    "description": "Short snippet of the video description...",
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
]

Rendering Results

Always present results as a markdown table with the video title rendered as a clickable link. Use this format:

| # | Title | Channel | Duration | Views | Published | |---|-------|---------|----------|-------|-----------| | 1 | Video title | Channel Name | 3:32 | 1,234,567 views | 2 days ago |

How It Works

1. Fetches the YouTube search results page for the given query
2. Extracts the embedded ytInitialData JSON from the HTML response
3. Parses video renderers from the search result contents
4. Returns structured JSON to stdout

No YouTube API key is required. The script scrapes public YouTube search pages using the same technique a browser would use.

Error Handling

• Errors are written to stderr so they don't interfere with JSON output on stdout
• Non-zero exit code on failure
• Gracefully handles missing fields in video data (returns null for unavailable fields)