# shutterstock-cli
[](https://opensource.org/licenses/MIT) [](https://github.com/psf/black)
A command-line utility that allows you to interact with the Shutterstock public API. For more information about the CLI and the API, see the [Shutterstock API reference](https://api-reference.shutterstock.com/).
## Installation
The Shutterstock CLI is available on the [Python Package Index (PyPI)](https://pypi.org/project/shutterstock-cli/). You can install it using pip.
``` bash
pip install shutterstock-cli
```
## Authentication
### Basic authentication
All endpoints in the Shutterstock API require authentication.
The API accepts HTTP basic authentication for some endpoints and OAuth authentication for all endpoints.
The API accepts HTTP basic authentication (also known as _basic authentication_) for some endpoints that do not access specific customer information.
Follow these steps to use basic authentication:
1. Create an account at https://www.shutterstock.com if you don't already have one.
2. Set up an application at https://www.shutterstock.com/account/developers/apps and get the consumer key and consumer secret from the application.
3. Export the consumer key and consumer secret as environment variables:
```bash
export SHUTTERSTOCK_KEY='YOUR_KEY'
export SHUTTERSTOCK_SECRET='YOUR_SECRET'
```
### OAuth authentication
Most endpoints require OAuth 2.0 authentication.
In this type of authentication, you use an application and an individual user's login credentials to obtain a token.
Then you can use that token as credentials for API requests in place of a user name and password.
Some endpoints require one or more _scopes_, or permissions, which let the user control what the application can do with the token.
For example, to edit a user's collections, the token must include the `collections.edit` scope.
Applications can request multiple tokens with different scopes or a single token with multiple scopes.
#### Getting tokens from your account page
As a shortcut, you can get a token directly from an application on your account page:
1. Create an account at https://www.shutterstock.com if you don't already have one.
2. Set up an application at https://www.shutterstock.com/account/developers/apps.
3. On the application details page, under **Token**, click **Generate token**.
4. On the Select scopes page, select the scopes for the token.
The token automatically has scopes that allow it to run basic tasks.
You can add scopes that allow it to access your licenses and collections.
5. Click **Continue**.
6. In the popup window, sign in to your shutterstock.com account.
The popup window shows the token. Copy it immediately, because it is shown only once.
The token is valid until the user account that you logged in with changes its password or email address.
Keep this token private, because other people could use it to access the account's subscriptions and media.
To use this token to authenticate your CLI commands, set it as the value of the `SHUTTERSTOCK_API_TOKEN` environment variable:
```bash
export SHUTTERSTOCK_API_TOKEN='YOUR_BEARER_TOKEN'
```
## Usage
Run `shutterstock --help` to see the available commands. You can also run shutterstock groupName --help or shutterstock groupName commandName --help to get help on a group of commands or on an individual command.
```bash
Usage: shutterstock [OPTIONS] COMMAND [ARGS]
Options:
--help Show this message and exit.
Commands are organized into these groups. To get a list of commands in a group, run shutterstock groupName --help.
Groups:
ai
audio
contributors
cv
editorial
images
test
user
videos
```
### Formatting JSON Output
If you would like to colorize the JSON response output you can set the `SHUTTERSTOCK_CLI_COLORIZE_OUTPUT` environment variable:
```bash
export SHUTTERSTOCK_CLI_COLORIZE_OUTPUT='true'
```
### Sandbox
To make requests to the licensing sandbox API instead of the main API, set the `SHUTTERSTOCK_SANDBOX` environment variable to true.
For more information about the sandbox, see https://api-reference.shutterstock.com/#licensing-and-downloading-licensing-sandbox.
```bash
export SHUTTERSTOCK_SANDBOX='true'
```
### Examples
Search for images of boats with an aspect ratio of 1.6.
```bash
shutterstock images search-images --query boats --aspect-ratio 1.6
```
Get information about an image, including a URL to a preview image and the sizes that it is available in.
```bash
shutterstock images get-image 1269188995
```
Get a list of existing image licenses for a specified time period.
```bash
shutterstock images get-image-license-list --start-date 2020-03-03T12:00:00Z --end-date 2020-03-04T12:00:00Z
```
Get images that are visually similar to an image that you specify.
```bash
shutterstock images get-similar-images 1269188995 --language en --per-page 200 --view minimal
```
License an image.
```bash
shutterstock images license-images path/to/payload.json --subscription-id s123abc
```
Get your image license history over a specified time period.
```bash
shutterstock images get-image-license-list --start-date 2021-01-01T12:00:00Z --end-date 2021-03-01T12:00:00Z
```
Get the public URL of the image that you have already received a license for.
```bash
shutterstock images download-image license-id-123 payload.json
```
For more examples, see the [Shutterstock API reference](https://api-reference.shutterstock.com/).
## Development
**Creating virtual environment**
```bash
python3 -m venv [NAME_FOR_YOUR_VIRTUAL_ENV]
```
**Activating virtual environment**
```bash
source [NAME_FOR_YOUR_VIRTUAL_ENV]/bin/activate
```
**Install app in virtual environment**
```bash
python setup.py install
```
**Install the requirements**
```bash
pip3 install -r requirements.txt
```
**Utilize installed app**
```bash
shutterstock --help
```
**Deactivating virtual environment**
You can deactivate the virtual environment by simply running the command below.
```bash
deactivate
```
### Running Tests
```
coverage run --omit 'env/*' -m unittest tests/*.py && coverage report -m
```
### Contributing
- Fork the project and clone locally.
- Create a new branch for what you're going to work on.
- Push to your origin repository.
- Create a new pull request in GitHub.
Raw data
{
"_id": null,
"home_page": "https://github.com/shutterstock/shutterstock-cli",
"name": "shutterstock-cli",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "shutterstock,api,images,videos,audio",
"author": "Shutterstock",
"author_email": "tech.api.team@shutterstock.com",
"download_url": "https://files.pythonhosted.org/packages/e5/0b/d37a20bf10256d165e11d7467602fdb71221aa46861e0f46ef5aa4f807bb/shutterstock-cli-1.1.38.tar.gz",
"platform": null,
"description": "# shutterstock-cli\n\n[](https://opensource.org/licenses/MIT) [](https://github.com/psf/black)\n\nA command-line utility that allows you to interact with the Shutterstock public API. For more information about the CLI and the API, see the [Shutterstock API reference](https://api-reference.shutterstock.com/).\n\n## Installation\n\nThe Shutterstock CLI is available on the [Python Package Index (PyPI)](https://pypi.org/project/shutterstock-cli/). You can install it using pip.\n\n``` bash\npip install shutterstock-cli\n```\n\n## Authentication\n\n### Basic authentication\n\nAll endpoints in the Shutterstock API require authentication.\nThe API accepts HTTP basic authentication for some endpoints and OAuth authentication for all endpoints.\n\nThe API accepts HTTP basic authentication (also known as _basic authentication_) for some endpoints that do not access specific customer information.\nFollow these steps to use basic authentication:\n\n1. Create an account at https://www.shutterstock.com if you don't already have one.\n2. Set up an application at https://www.shutterstock.com/account/developers/apps and get the consumer key and consumer secret from the application.\n3. Export the consumer key and consumer secret as environment variables:\n\n```bash\nexport SHUTTERSTOCK_KEY='YOUR_KEY'\nexport SHUTTERSTOCK_SECRET='YOUR_SECRET'\n```\n\n### OAuth authentication\n\nMost endpoints require OAuth 2.0 authentication.\nIn this type of authentication, you use an application and an individual user's login credentials to obtain a token.\nThen you can use that token as credentials for API requests in place of a user name and password.\n\nSome endpoints require one or more _scopes_, or permissions, which let the user control what the application can do with the token.\nFor example, to edit a user's collections, the token must include the `collections.edit` scope.\nApplications can request multiple tokens with different scopes or a single token with multiple scopes.\n\n#### Getting tokens from your account page\n\nAs a shortcut, you can get a token directly from an application on your account page:\n\n1. Create an account at https://www.shutterstock.com if you don't already have one.\n2. Set up an application at https://www.shutterstock.com/account/developers/apps.\n3. On the application details page, under **Token**, click **Generate token**.\n4. On the Select scopes page, select the scopes for the token.\n The token automatically has scopes that allow it to run basic tasks.\n You can add scopes that allow it to access your licenses and collections.\n5. Click **Continue**.\n6. In the popup window, sign in to your shutterstock.com account.\n\nThe popup window shows the token. Copy it immediately, because it is shown only once.\nThe token is valid until the user account that you logged in with changes its password or email address.\n\nKeep this token private, because other people could use it to access the account's subscriptions and media.\n\nTo use this token to authenticate your CLI commands, set it as the value of the `SHUTTERSTOCK_API_TOKEN` environment variable:\n\n```bash\nexport SHUTTERSTOCK_API_TOKEN='YOUR_BEARER_TOKEN'\n```\n\n## Usage\n\nRun `shutterstock --help` to see the available commands. You can also run shutterstock groupName --help or shutterstock groupName commandName --help to get help on a group of commands or on an individual command.\n\n```bash\nUsage: shutterstock [OPTIONS] COMMAND [ARGS]\n\nOptions:\n --help Show this message and exit.\n\nCommands are organized into these groups. To get a list of commands in a group, run shutterstock groupName --help.\n\nGroups:\n ai\n audio\n contributors\n cv\n editorial\n images\n test\n user\n videos\n```\n\n### Formatting JSON Output\n\nIf you would like to colorize the JSON response output you can set the `SHUTTERSTOCK_CLI_COLORIZE_OUTPUT` environment variable:\n\n```bash\nexport SHUTTERSTOCK_CLI_COLORIZE_OUTPUT='true'\n```\n\n### Sandbox\n\nTo make requests to the licensing sandbox API instead of the main API, set the `SHUTTERSTOCK_SANDBOX` environment variable to true.\n\nFor more information about the sandbox, see https://api-reference.shutterstock.com/#licensing-and-downloading-licensing-sandbox.\n\n```bash\nexport SHUTTERSTOCK_SANDBOX='true'\n```\n\n### Examples\n\nSearch for images of boats with an aspect ratio of 1.6.\n\n```bash\nshutterstock images search-images --query boats --aspect-ratio 1.6\n```\n\nGet information about an image, including a URL to a preview image and the sizes that it is available in.\n\n```bash\nshutterstock images get-image 1269188995\n```\n\nGet a list of existing image licenses for a specified time period.\n\n```bash\nshutterstock images get-image-license-list --start-date 2020-03-03T12:00:00Z --end-date 2020-03-04T12:00:00Z\n```\n\nGet images that are visually similar to an image that you specify.\n\n```bash\nshutterstock images get-similar-images 1269188995 --language en --per-page 200 --view minimal\n```\n\nLicense an image.\n\n```bash\nshutterstock images license-images path/to/payload.json --subscription-id s123abc\n```\n\nGet your image license history over a specified time period.\n\n```bash\nshutterstock images get-image-license-list --start-date 2021-01-01T12:00:00Z --end-date 2021-03-01T12:00:00Z\n```\n\nGet the public URL of the image that you have already received a license for.\n\n```bash\nshutterstock images download-image license-id-123 payload.json\n```\n\nFor more examples, see the [Shutterstock API reference](https://api-reference.shutterstock.com/).\n\n## Development\n\n**Creating virtual environment**\n\n```bash\npython3 -m venv [NAME_FOR_YOUR_VIRTUAL_ENV]\n```\n\n**Activating virtual environment**\n\n```bash\nsource [NAME_FOR_YOUR_VIRTUAL_ENV]/bin/activate\n```\n\n**Install app in virtual environment**\n\n```bash\npython setup.py install\n```\n\n**Install the requirements**\n\n```bash\npip3 install -r requirements.txt\n```\n\n**Utilize installed app**\n\n```bash\nshutterstock --help\n```\n\n**Deactivating virtual environment**\n\nYou can deactivate the virtual environment by simply running the command below.\n\n```bash\ndeactivate\n```\n\n### Running Tests\n\n```\ncoverage run --omit 'env/*' -m unittest tests/*.py && coverage report -m\n```\n\n### Contributing\n\n- Fork the project and clone locally.\n- Create a new branch for what you're going to work on.\n- Push to your origin repository.\n- Create a new pull request in GitHub.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A command-line utility that allows you to interact with the Shutterstock public API.",
"version": "1.1.38",
"project_urls": {
"Homepage": "https://github.com/shutterstock/shutterstock-cli"
},
"split_keywords": [
"shutterstock",
"api",
"images",
"videos",
"audio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6837ac9174ed6c74f48b069a90f82c0ea334fe63fd7f24e2744c8015d548ca4",
"md5": "46c647c472a5d209fc122f8c5eec7e5e",
"sha256": "e7a94daa969563cf56489bcd33b17ad744c3446216469171060925a41ec53ef1"
},
"downloads": -1,
"filename": "shutterstock_cli-1.1.38-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "46c647c472a5d209fc122f8c5eec7e5e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 25618,
"upload_time": "2024-01-22T18:36:03",
"upload_time_iso_8601": "2024-01-22T18:36:03.541240Z",
"url": "https://files.pythonhosted.org/packages/e6/83/7ac9174ed6c74f48b069a90f82c0ea334fe63fd7f24e2744c8015d548ca4/shutterstock_cli-1.1.38-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e50bd37a20bf10256d165e11d7467602fdb71221aa46861e0f46ef5aa4f807bb",
"md5": "6ecaf16ca1cd405c27162ff6574cd21f",
"sha256": "e9ebf35f1dbe76ba77f97f6b748ae8593e90605e3a12b9a3ae469e32dc991d01"
},
"downloads": -1,
"filename": "shutterstock-cli-1.1.38.tar.gz",
"has_sig": false,
"md5_digest": "6ecaf16ca1cd405c27162ff6574cd21f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19521,
"upload_time": "2024-01-22T18:36:05",
"upload_time_iso_8601": "2024-01-22T18:36:05.495707Z",
"url": "https://files.pythonhosted.org/packages/e5/0b/d37a20bf10256d165e11d7467602fdb71221aa46861e0f46ef5aa4f807bb/shutterstock-cli-1.1.38.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-22 18:36:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shutterstock",
"github_project": "shutterstock-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "shutterstock-cli"
}
JSON
