Cloudinary CLI reference

The Cloudinary CLI (Command Line Interface) enables you to interact with Cloudinary through the command line. For example, you can perform Admin and Upload API operations by typing commands into a terminal without having to spend time setting up a formal coding environment. Additional helper commands are provided to help you to try out transformations, optimizations, and other common actions with minimal effort. You can also combine CLI commands in a batch file to automate laborious tasks.

 

We invite you to try the free Introduction to Cloudinary's CLI online course, where you can get an overview of the many upload, management, and transformation options that Cloudinary provides, and learn how to easily apply them via the command line.

Installation and configuration

1. Prerequisite: To use the Cloudinary CLI, you need Python 3.6 or later. You can install Python from https://www.python.org. The Python Package Installer (pip) is installed with it.

2. To install the Cloudinary CLI, run:

3. To make all your cld commands point to your Cloudinary product environment, set up your CLOUDINARY_URL environment variable, which takes the form <API_KEY>:<API_SECRET>@<CLOUD_NAME>.

   For example, to set a temporary environment variable:

   • On Mac or Linux:

   • On Windows:

   You may prefer to set up a persistent environment variable, but be aware that you could put your API secret at risk by storing it in your shell's startup script.
   Tip

   Copy the API environment variable format from the API Keys page of the Cloudinary Console Settings. Replace <your_api_key> and <your_api_secret> with your actual values, while your cloud name is already correctly included in the format.

4. Check your configuration by running:

   A response of the following form is returned:

Setting configuration parameters

You can set any of the configuration parameters by appending them to your CLOUDINARY_URL environment variable as a query string, either when setting up your default configuration or when setting up alternative configurations using the config command.

For example, to use the Cloudinary data center at https://api-eu.cloudinary.com and set your custom domain name to domain_name.com, add the upload_prefix and cname parameters to the environment variable:

You can see which configuration parameters are set by running the cld config command:

Upgrade

To upgrade your installation of the Cloudinary CLI to the latest version, enter:

Basic commands

To help you get started, there are some basic commands you can use.

For a list of commands, enter:

To see the version of CLI, underlying Python SDK and Python, enter:

To see the available Admin API methods, enter:

To see the available upload API methods, enter:

To show the usage for the search API, enter:

To see the available utility methods, enter:

See the Command overview for a listing of all available commands, or the Command reference for syntax details and usage examples of the commands.

Take a look at this video to see the CLI being installed and configured, plus some basic commands in action:

Tutorial contents

---

Command overview

All Cloudinary CLI commands start with cld. The general syntax for the commands is as follows:

For example, the following command runs the resources_by_moderation method in the Admin API, limiting information output to the ERROR level. It returns details of up to 40 raw files that have been rejected by the Perception Point Malware Detection anti-malware plugin, saving the output in a file called 'output.txt'.

This command can be broken down as follows:

Syntax	Example
cli options	-v ERROR
command	admin
command options	--save output.txt -o max_results 40 -o resource_type raw
method	resources_by_moderation
method parameters	perception_point rejected

Optional parameters can either be specified as command options (as in the above example) or using a syntax that assigns values.

• If specified as command options they can be positioned either before or, more intuitively, after the method.
• If specified using the assign syntax they must be specified after the method and any required parameters.

The example above can therefore also be entered as:

or (using the syntax that assigns values):

CLI options

CLI OPTION	DESCRIPTION
-c, --config (env_var_url)	Tell the CLI which product environment to run the command on by specifying an environment variable. This overrides the default configuration.
-C, --config_saved (name)	Tell the CLI which product environment to run the command on by specifying a saved configuration. See the config command. This overrides the default configuration.
-v, --verbosity (level)	Specify the level of information output: CRITICAL, ERROR, WARNING, INFO or DEBUG.
--version	Show the version of the CLI, the underlying Python SDK and Python.
--help	Show help.

Commands

API commands

COMMAND	DESCRIPTION
admin	Run methods from the Admin API.
uploader	Run methods from the Upload API.
search	Run the search method from the Admin API.
provisioning	Run methods from the Provisioning API.

File Management

COMMAND	DESCRIPTION
migrate	Migrate a list of external media files, referenced as URLs with the same prefix, to Cloudinary.
sync	Synchronize between a local folder and a Cloudinary folder.
upload_dir	Upload a folder of assets and maintain the folder structure.
regen_derived	Regenerate derived assets pertaining to a named transformation or transformation string.

Helpers

COMMAND	DESCRIPTION
utils	Run utility methods.
make	Return template code for implementing the specified Cloudinary widget or functionality.
url	Generate a Cloudinary URL.

Configuration

COMMAND	DESCRIPTION
config	Manage product environment configurations.

---

Command reference

admin

The admin command enables you to run any methods that can be called through the Admin API. The Admin API is a rate-limited API that provides full control of all uploaded media assets (resources), fetched social profile pictures, generated transformations and more.

See the Admin API reference for details about each of the methods.

Syntax

Command options

OPTION	DESCRIPTION
-o, --optional_parameter (param)	Pass optional parameters as raw strings.
-O, --optional_parameter_parsed (param)	Pass optional parameters as interpreted strings.
-ls, --ls	List all available methods in the Admin API.
--save (filename)	Save output to a file.
-d, --doc	Open the Admin API reference in a browser.
--help	Show help.

Methods

Use cld admin to list all of the available Admin API methods. Then refer to the Admin API reference to see the parameters applicable to each method.

For example, the method resources_by_tag has a required parameter tag, and various optional parameters. To list up to ten videos (using the optional parameters max_results and resource_type) tagged with "animals", enter:

Examples

Show all the tags in your product environment.

List all the resource types in a product environment:

Create a named transformation, then use the named transformation in an upload preset.

---

uploader

The uploader command enables you to run any methods that can be called through the upload API. The upload API enables you to upload and manage media assets in your Cloudinary product environment.

See the Upload API reference for details about each of the methods.

Syntax

Command options

OPTION	DESCRIPTION
-o, --optional_parameter (param)	Pass optional parameters as raw strings.
-O, --optional_parameter_parsed (param)	Pass optional parameters as interpreted strings.
-ls, --ls	List all available methods in the Upload API.
--save (filename)	Save output to a file.
-d, --doc	Open the Upload API reference in a browser.
--help	Show help.

Methods

Use cld uploader to list all of the available upload API methods. Then refer to the Upload API reference to see the parameters applicable to each method.

For example, the method rename has two required parameters, from_public_id and to_public_id, and various optional parameters. To rename photo1 to photo2, making photo2 private and invalidating photo1 on the CDN (using the optional parameters to_type and invalidate), enter:

Examples

Imagine that you have a bunch of photos that you want to turn into a slide show. You can tag them on upload and then create an animated GIF from the images. In the following example, we have a local folder containing images of birds. The bash script below runs from within that folder and uploads each JPG in the local folder to a folder in Cloudinary called "birds", adding the tags "bird", "feathers" and "beak". It then uses the multi method to create an animated GIF from all images with the "bird" tag, applying a delay of 1300 ms between each frame.

The result is a slide show of the bird images:

Here's another example of the multi method in action:

Tutorial contents

And here are some more upload API methods being used to generate an image sprite from pages of a PDF:

Tutorial contents

---

search

The search command runs the Admin API search method. This method allows you to filter and retrieve information on all the assets in your product environment with the help of query expressions in a Lucene-like query language.

See the search method documentation for more details.

Syntax

Command options

OPTION	DESCRIPTION
-f, --with_field (asset_attributes)	Specify which non-default asset attributes to include in the result as a comma separated list, for example -f tags,context. Alternatively, you can include more than one of these options, for example, -f tags -f context.
-fi, --fields (asset_attributes)	Specify which asset attributes to include in the result (together with a subset of the default attributes) as a comma separated list, for example -fi tags,context. Alternatively, you can include more than one of these options, for example, -fi tags -fi context. This overrides any values specified for with_field.
-s, --sort_by (field) (asc,desc)	Sort search results by the specified field ascending or descending.
-a, --aggregate (aggr_param)	Specify the attribute for which an aggregation count should be calculated and returned.
-n, --max_results (integer)	The maximum number of results to return. Default: 10, maximum: 500.
-c, --next_cursor (cursor)	Continue a search using an existing cursor.
-A, --auto_paginate	Return all results. This may call the Admin API multiple times.
-F, --force	Skip confirmation when running auto_paginate.
-ff, --filter_fields (fields)	Specify which attributes to show in the response as a comma separated list, for example -ff format,public_id. Alternatively, you can include more than one of these options, for example, -ff format -ff public_id. None of the other attributes will be shown in the response. Can be used to filter default fields as well as those added through the use of with_field or fields.
-t, --ttl (integer)	Set the cacheable search URL TTL in seconds. Default: 300.
-u, --url	Build a cacheable search URL.
--json (filename)	Save JSON output to a file.
--csv (filename)	Save CSV output to a file.
-d, --doc	Open the Search API documentation page.
--help	Show help.

expression

The search expression. For supported expressions, see Expressions.

Examples

Find images tagged with "bird", that have been uploaded within the last day, and are larger than 100 kB in size. In the response, include the tags field, sort the results by public_id in ascending order, and limit the returned results to 30 resources:

Sample output:

This time, let the response show only the public_id and the tags (-ff public_id,tags):

Sample output:

---

provisioning

The provisioning command enables you to run any methods that can be called through the provisioning API. The provisioning API enables you to create and manage product environments, users and user groups. The provisioning API is available for Enterprise plan upon request.

See the Provisioning API reference for details about each of the methods.

To call provisioning methods:

• Your product environment needs to be set up for provisioning.

• You need to set up your CLOUDINARY_ACCOUNT_URL environment variable, which takes the form <PROVISIONING_API_KEY>:<PROVISIONING_API_SECRET>@<ACCOUNT_ID>. To set a temporary environment variable, for example:

  • On Mac or Linux:

  • On Windows:

  Tip

  You can copy and paste the component parts of your CLOUDINARY_ACCOUNT_URL from the Provisioning API Access section of the Account page in the Cloudinary Console Settings. If your account is not set up for provisioning (available upon request for Enterprise plans), you won't see this section.

Syntax

Command options

OPTION	DESCRIPTION
-o, --optional_parameter (param)	Pass optional parameters as raw strings.
-O, --optional_parameter_parsed (param)	Pass optional parameters as interpreted strings.
-ls, --ls	List all available methods in the Provisioning API.
--save (filename)	Save output to a file.
-d, --doc	Open the Provisioning API reference in a browser.
--help	Show help.

Methods

Use cld provisioning to list all of the available provisioning API methods. Then refer to the Provisioning API reference to see the parameters applicable to each method.

For example, the method, update_user, has one required parameter, user_id, and various optional parameters. To update the role of a user with id 7f08f1f1fc910bf1f25274aef11d27 to admin, enter:

Examples

Create a product environment called docs-demo, with a cloud called docs-demo-cloud, based on the existing product environment with ID, 0918b03ea306482e4858ee1ac2e7c8:

Sample response:

Create a user called John Smith, whose email address is johnsmith@example.com, with the media_library_user role and access to product environments with IDs: 0918b03ea306482e4858ee1ac2e7c8 and 7ad7f4e93ba3f349ee63642fb68e42:

Sample response:

---

migrate

Use the migrate command to migrate a list of external media files to Cloudinary. The URLs of the files to migrate are listed in a separate file and must all have the same prefix.

Syntax

Command options

OPTION	DESCRIPTION
-d, --delimiter (string)	The separator used between the URLs. If no delimiter is specified, a new line is assumed as the separator.
-v, --verbose	Output information for each uploaded file.
--help	Show help.

upload_mapping

An auto-upload URL mapping that you have configured in your product environment Upload Settings. Set upload_mapping to the name of the mapped folder.

file

The name of the file containing the URLs that each have the same URL prefix as specified in the auto-upload URL mapping.

Example

You have a file of URLs that point to assets that you want to migrate to your Cloudinary product environment. In this example, all the assets are prefixed by 'https://upload.wikimedia.org/wikipedia/commons/' and the URLs in the file are delimited by semicolons.

The file, called url_file.txt, looks like this:

https://upload.wikimedia.org/wikipedia/commons/c/cb/Eden_Gardens_under_floodlights_during_a_match.jpg;https://upload.wikimedia.org/wikipedia/commons/d/dc/Historical_cricket_bat_art.jpg;https://upload.wikimedia.org/wikipedia/commons/a/ae/Olympic_flag.jpg;https://upload.wikimedia.org/wikipedia/commons/3/35/Olympic-flag-Victoria.jpg

First, configure an auto-upload URL mapping in your product environment Upload Settings that maps a Cloudinary folder, for example, 'remote_media', to the URL prefix 'https://upload.wikimedia.org/wikipedia/commons/'. The folder will be created in Cloudinary automatically if it does not already exist.

You can create the upload mapping in the Cloudinary Console Upload Settings, or using the CLI as follows:

Then, run this command to migrate all the assets in url_file.txt to the remote_media folder in your Cloudinary product environment, returning 'verbose' output:

Sample verbose output:

---

sync

The sync command synchronizes between a local folder and a Cloudinary folder, maintaining the folder structure.

Syntax

Command options

OPTION	DESCRIPTION
--push	Push changes from your local folder to your Cloudinary folder.
--pull	Pull changes from your Cloudinary folder to your local folder.
-H, --include-hidden	Include hidden files in the sync.
-w, --concurrent_workers (integer)	Specify the number of concurrent network threads. Default: 30.
-F, --force	Skip confirmation when deleting files.
-K, --keep-unique	Keep unique files in the destination folder.
-D, --deletion-batch-size (integer)	Specify the batch size for deleting remote assets. Default: 30.
-o, --optional_parameter (param)	An optional upload parameter to pass as a raw string.
-O, --optional_parameter_parsed (param)	An optional upload parameter to pass as an interpreted string.
--help	Show help.

local_folder

Your local folder that you want to synchronize with your Cloudinary folder.

cloudinary_folder

The full path of the Cloudinary folder that you want to synchronize with your local folder. You can specify a path by separating folders with a forward slash.

• In fixed folder mode, the cloudinary_folder is the first part of the public ID of the uploaded assets (up to the final forward slash).
• In dynamic folder mode, the cloudinary_folder is the asset folder of the uploaded assets.

Example

Push changes from the local folder, my_images, to the Cloudinary folder, my_cld_images/my_images.

Sample output:

Subsequently, delete two files from the Cloudinary folder. Now pull the changes back down to the local folder with the -F option so as not to be prompted for confirmation to delete files:

Sample output:

---

upload_dir

Use the upload_dir command to upload a folder of assets, maintaining the folder structure.

Syntax

Command options

OPTION	DESCRIPTION
-g, --glob-pattern (pattern)	The glob pattern. For example, use **/*.jpg to upload only JPG files.
-H, --include-hidden	Include hidden files.
-o, --optional_parameter (param)	An optional upload parameter to pass as a raw string.
-O, --optional_parameter_parsed (param)	An optional upload parameter to pass as an interpreted string.
-t, --transformation (transformation)	The transformation to apply on all uploads.
-f, --folder (folder)	The full path in Cloudinary where you want to upload the assets. You can specify a whole path, for example path1/path2/path3. Any folders that do not exist are automatically created. In the legacy fixed folder mode, the specified folder path is the first part of the public ID of the uploaded assets (up to the final forward slash). In dynamic folder mode, the path is the asset_folder of the uploaded assets.
-p, --preset (upload_preset)	The upload preset to use.
-e, --exclude-dir-name	When this option is used, the contents of the parent directory are uploaded, but not the parent directory itself.
-w, --concurrent_workers (integer)	Specify the number of concurrent network threads. Default: 30.
-d, --doc	Show the documentation for upload_dir.
--help	Show help.

local_folder

Your local folder that you want to upload to Cloudinary. If this argument is omitted, the contents of the current folder are uploaded.

Examples

Upload the local folder, my_images, and all its contents and sub-folders to the Cloudinary folder my_images_on_cloudinary, overwriting existing files.

This results in the following folder structure in Cloudinary:

    Home
    +--my_images_on_cloudinary
    |  +-- my_images
    |  |   +-- <all assets and sub-folders of my_images>

As above, but excluding the parent folder name, my_images.

This results in the following folder structure in Cloudinary:

    Home
    +--my_images_on_cloudinary
    |  +-- <all assets and sub-folders of my_images>

This video shows the upload_dir command in action:

Tutorial contents

---

regen_derived

Use the regen_derived command to regenerate all derived assets pertaining to a specific named transformation, or transformation string. Use this after updating a named transformation to invalidate and repopulate the cache with up-to-date versions of the assets.

Syntax

Command options

OPTION	DESCRIPTION
-enu, --eager_notification_url (URL)	A webhook notification URL.
-ea, --eager_async	Generate asynchronously.
-A, --auto_paginate	Auto-paginate Admin API calls.
-F, --force	Skip the initial confirmation.
-n, --max_results (integer)	The maximum number of results to return. Default: 10, maximum: 500.
-w, --concurrent_workers (integer)	Specify the number of concurrent network threads. Default: 30.
--help	Show help.

transformation_name

Either the name of a named transformation, for example, black-border, or a transformation string, for example t_black-border/a_50/l_icon/fl_layer_apply,g_west.

Examples

Asynchronously regenerate all assets that have been derived using the named transformation called small-square, skipping the initial confirmation, and notify a specific webhook.

Sample response:

Regenerate all assets that have been derived using the transformation string t_small-square/f_avif,fl_aavif/a_30/jpg, skipping the initial confirmation.

Sample response:

---

utils

The utils command enables you to run Cloudinary utility methods.

Syntax

Command options

OPTION	DESCRIPTION
-o, --optional_parameter (param)	Pass optional parameters as raw strings.
-O, --optional_parameter_parsed (param)	Pass optional parameters as interpreted strings.
-ls, --ls	List all available utility methods.
--help	Show help.

Methods

Use cld utils to list all of the available utility methods. Refer to the links in the table below to see the parameters applicable to each method.

Method definition	Learn more
api_sign_request	Using Cloudinary backend SDKs to generate SHA authentication signatures
cloudinary_url	Embedding images in web pages using SDKs
download_archive_url	download_archive_url syntax
download_backedup_asset	download_backup method
download_folder	download_folder syntax
download_zip_url	download_zip_url syntax
private_download_url	Providing time-limited access to private media assets
verify_api_response_signature	Verifying signatures in the JSON response
verify_notification_signature	Verifying notification signatures

Examples

Generate a signature, where the parameters to sign are '{"timestamp": 1595793040, "public_id": "flower"}' and the API secret is 323127161127519:

Sample output:

Generate the URL to deliver the asset with public ID, sample, scaled to a width of 300 pixels and a height of 100 pixels.

Sample output:

---

make

The make command returns template code for implementing the specified Cloudinary widget or functionality.

Syntax

Command options

OPTION	DESCRIPTION
-ll, --list-languages	List available languages.
-lt, --list-templates	List available templates.
--help	Show help.

language

AVAILABLE LANGUAGES
python
html (default)
node
ruby

template

TEMPLATE	DESCRIPTION
find_all_empty_folders	Return template code for finding empty folders.
media_library_widget	Return template code for the Media Library Widget.
product_gallery	Return template code for the Product Gallery.
upload_widget	Return template code for the Upload Widget.
video_player	Return template code for the Video Player.

Examples

Generate sample code for implementing a basic upload widget in your web page.

Sample output:

Generate sample Python code for finding all empty folders.

Sample output:

---

url

The url command generates a Cloudinary URL, which you can optionally open in your browser.

Syntax

Command options

OPTION	DESCRIPTION
-rt, --resource_type [image, video, raw]	The asset type.
-t, --type [upload, private, authenticated, fetch, list, url2png]	The delivery type.
-o, --open	Generate the derived asset and open it in your browser.
-s, --sign	Generate as a signed URL.
--help	Show help.

transformation

The transformation that you want to perform on the asset. Use the URL syntax as described in the Transformation URL API Reference.

Examples

Perform the following transformation on the image with public ID docs/animals_on_road:

• Resize to width to 400 pixels using the thumb cropping mode with automatic gravity
• Apply a vectorize effect using 10 colors and a detail of 60%
• Add a vignette effect with a strength of 40.

Sample output:

Use the URL2PNG add-on to capture a screenshot of the top part of the Cloudinary home page, apply a grayscale effect to the captured image, and open the transformed image in the browser. As the URL2PNG add-on requires URLs to be signed, the -s option is used.

Sample output:

---

config

A configuration is a reference to a specified Cloudinary product environment via its environment variable. You set the default configuration during installation and configuration. Using different configurations allows you to access different Cloudinary product environments.

The config command displays the current configuration and lets you manage additional configurations.

You can specify the environment variable of additional Cloudinary product environments either explicitly (-c option) or as a saved configuration (-C option).

For example, using the -c option:

Whereas using the saved configuration "accountx":

You can create, delete and list saved configurations using the config command.

See also: Setting configuration parameters

Syntax

Options

OPTION	DESCRIPTION
-n, --new (name env_var_url)	Create and name a configuration from a Cloudinary environment variable.
-ls, --ls	List all saved configurations.
-s, --show (name)	Show details of a specified configuration.
-rm, --rm (name)	Delete a specified configuration.
-url, --from_url (env_var_url)	Create a configuration from a Cloudinary environment variable. The configuration name is the cloud name.
--help	Show help.

Examples

In these examples, we use a made up environment variable.

Display the current configuration.

Create an additional configuration named accountx, display its details, show the upload presets that are configured in this product environment, then delete the configuration.

Create an additional configuration from an environment variable. The configuration is automatically given the same name as the cloud name, in this case cloud_name. Then upload a picture to the product environment, applying relevant tags.

List all saved configurations to a file called configs.txt, then delete all the configurations.