Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/MehediH/Bulksplash

A simple command line tool that lets you bulk download images from Unsplash
https://github.com/MehediH/Bulksplash

command-line command-line-tool images stock-images unsplash

Last synced: 15 days ago
JSON representation

A simple command line tool that lets you bulk download images from Unsplash

Host: GitHub
URL: https://github.com/MehediH/Bulksplash
Owner: MehediH
License: gpl-3.0
Created: 2017-03-25T23:22:06.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2023-03-20T16:44:25.000Z (over 1 year ago)
Last Synced: 2024-10-14T04:24:32.436Z (about 2 months ago)
Topics: command-line, command-line-tool, images, stock-images, unsplash
Language: JavaScript
Homepage: https://www.npmjs.com/package/bulksplash
Size: 1.25 MB
Stars: 533
Watchers: 15
Forks: 56
Open Issues: 12
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

jimsghstars - MehediH/Bulksplash - A simple command line tool that lets you bulk download images from Unsplash (JavaScript)

README

# Bulksplash

### A simple command line tool that lets you bulk download images from Unsplash, previously known as Unsplash Bulk Downloader.

![screenshot](https://raw.githubusercontent.com/MehediH/Bulksplash/images/demo.gif)

## Quick Start

To use Bulksplash, you need to [install Node.js](https://nodejs.org/en/download/). Once you have Node.js installed, you can simple use the `npx` command to run Bulksplash:

`npx bulksplash`

This will automatically download and let you use Bulksplash. To be able to use Bulksplash wherever you like, you can install it globally using `npm`:

`npm install bulksplash --g`

Once installed, you can simply run `bulksplash` from the terminal on any folder to download images from Unsplash.

## Obtaining an API key

To use Bulksplash, you NEED to obtain an API key for Unsplash. This can be done by [signing up here](https://unsplash.com/developers) and creating a Demo app. This will allow you to download 50 images per hour, but if you want to download more than that, you will need to apply for Production access via Unsplash Developers.

## Options

Prompts in the terminal will guide you through the options for downloading images, with some default values for quicker use. The prompts are as follows:

- `What is your API key?` - You need an API key for Unsplash to be able to use Bulksplash. [Get one here.](https://unsplash.com/developers)
- `Which directory do you want to save to?` - The folder you want to download the pictures to. _Defaults to your current directory_
- `Which images do you want to download?` - Whether you want to download images randomly or from a specific collection. _Defaults to random_
- `What search term?` - A search term, or blank for random images. _Defaults to blank_
- `Enter the URL of the Unsplash collection you want to download from ` - The link of the Unsplash Collection you want to download _Defaults to blank, needs to be a valid link_
- `How many images (up to 50)?` - The number of images to retrieve. _Defaults to 20_
- `Only featured images?` - Should it only get featured images, curated by Unsplash? _Defaults to `Yes`_
- `What orientation?` - What orientation should the images be? The options are `Mixed`, `Portrait`, `Landscape`, `Squarish`, or `Custom`. `Mixed` will get images regardless of orientation, while `Custom` allows you to choose a specific width and height. _Defaults to `Mixed`_
- `Width?` - For any orientation, choose the width of the returned images. This is required when the `Custom` orientation is selected. _Defaults to blank for original size_
- `Height?` - For `Custom` orientation, specify a height. This option is not displayed if the orientation is not
- `Export the credits for the photos to a .json file?` - Whether to generate the `bulksplash-credits.json` file with all the details about hte photographers. _Defaults to yes_

## Quick Usage

Bulksplash lets you directly use the tool without going through the prompt interface.

For example: `bulksplash --a=50 --d=basket -c=https://unsplash.com/collections/9454911 --f --j --k=API_KEY` will download 50 featured images from the "Basketball" collection into the "test" sub-folder and generate a credits file.

Available options:

- `--d`: the directory you want to save images to.
- `--c`: if you want to download images from a collection, enter the link of the Unsplash collection you want to download images from.
- `--q`: if you want to download images about something specific, you can enter a search query.
- `--a`: the number of images you want to download.
- `--w`: the width of the images.
- `--h`: the height of the images.
- `--o`: the orientation of the images ("landscape", "portrait", "squarish")
- `--f`: whether you want to download featured images.
- `--n`: the name scheme of the downloaded images (0 for `authorname-randomstring`, 1 for numbered list)
- `--j`: whether you want to generate a credits file.
- `--k`: your Unsplash API key.

---

Please feel free to contribute to this tiny project and make it better and [follow me on Twitter](https://twitter.com/mehedih_) for more projects like this!