gb-dl

A CLI for downloading Giant Bomb videos.

How to Use

Binaries

Visit the releases page and download the latest binary for your system.

gb-dl --api-key <YOUR_API_KEY> --video-name <string>

npx

Node Required

npx gb-dl --api-key <YOUR_API_KEY> --video-name <string>

More Examples

Options

API key may be provided via --api-key option or GIANTBOMB_TOKEN env variable.

Either --video-name, --video-guid, or --video-number must be provided.

Option	Type	Required	Description
--api-key	String	false*	Individual Giant Bomb API key.
--video-name	String	false*	Used to find matching video title.
--video-guid	String	false*	Used to grab a video by its GUID directly.
--video-number	Number	false*	Zero-based video index for provided show (most recent video is 0). Defaults to 0.
--video-number-reverse		false	Swaps direction of provided "--video-number" (oldest video is now 0).
--show-name	String	false	Used to find matching show title.
--only-premium		false	Filter search to only premium videos.
--only-free		false	Filter search to only free videos.
--quality	String	false	Specify quality of video to download. Defaults to highest. Other options: hd, high, low and mobile.
--date-after	String	false	Check if video was published after date before downloading (i.e. MM/DD/YYY, inclusive).
--date-before	String	false	Check if video was published before date before downloading (i.e. MM/DD/YYY, inclusive).
--out-dir	String	false	Specify output directory for video. Defaults to current working directory.
--add-guid-prefix		false	Prefixes the downloaded video with its associated GUID (e.g. "2300-14149 - Quick Look_ Forager.mp4")
--add-date-prefix		false	Prefixes the downloaded video with its publish date (e.g. "2021-05-08 - Quick Look_ Forager.mp4")
--info		false	Output video information instead of download.
--archive		false	Check archive before downloading.
--blocklist		false	Check blocklist before downloading.
--clean		false	Ignore cache when making query.
--debug		false	Show debug statements.
--health-check		false	Check the Giant Bomb API for ongoing issues.
--version		false	Output the version number.
--help		false	Output usage information.

Giant Bomb API

• Make sure to stay within the Giant Bomb API usage guidelines.
• The Giant Bomb API has an unmentioned account download limit of 100 videos per day.

Rate Limiting

• A one second delay between requests is added to avoid flooding the Giant Bomb API.
• gb-dl may need to make a few requests to find a video, so expect a short delay after starting.

Caching

• gb-dl will generate a gb-dl-cache.json in the current working directory when run in order to avoid hitting the Giant Bomb API repeatedly for the same set of data.
• Cached responses will be used for one hour.
• Adding --clean to the command will bypass the cache.
• Expired cache results will be removed on script start.

Archive

• If passed the --archive flag, gb-dl will generate/use a gb-dl-archive.json in the current working directory.
• Before downloading a video, it'll check if the video was downloaded previously and abort the download if found.

Blocklist

• If the --blocklist flag is passed, gb-dl will look up a gb-dl-blocklist.json in the current working directory.
• Before downloading a video it'll check if the video_show title is included in the blocklist and ignore the download if found.
• See Examples for an example blocklist.

More Examples