Gb-dl NPM | npm.io

gb-dl

A CLI for downloading Giant Bomb videos.

gb-dl example gif

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.

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.