> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. 

> **INFO**: CLI scripts should only be run locally or as part of server applications and never embedded in a client-side app so as not to expose your product environment API secret.

 We invite you to try the free **Introduction to Cloudinary's CLI** online courses (Part 1 and Part 2), where you can learn about the many upload, management, and transformation options that Cloudinary provides from 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](https://www.python.org/). The Python Package Installer (`pip`) is installed with it.
1. To install the Cloudinary CLI, run: 

    ```
    pip3 install cloudinary-cli
    ```
1. 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:

    ```
    export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name
    ```
    
    
    On Windows (Command Prompt):

    ```
    set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name
    ```
    
    
    On Windows (PowerShell):

    ```
    $Env:CLOUDINARY_URL="cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name"
    ```
    
    
    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](https://console.cloudinary.com/app/settings/api-keys) page of the Cloudinary Console Settings. Replace `<your_api_key>` and `<your_api_secret>` with your actual values. Your cloud name is already correctly included in the format.

1. If the `cld` command is not found after installation, your shell may not include the directory where `pip` installed executables. On **Mac or Linux**, add the Cloudinary CLI package's `bin` directory to your `PATH` for the current session:

    ```
    export PATH="$PATH:$(pip3 show cloudinary-cli | grep '^Location:' | sed 's/^Location:[[:space:]]*//')/bin"
    ```

    Use `pip` instead of `pip3` if that matches how you installed the CLI.

1. Check your configuration by running:

    ```
    cld config
    ```

    A response of the following form is returned:

    ```
    cloud_name:     <CLOUD_NAME>
    api_key:        <API_KEY>
    api_secret:     ***************<LAST_4_DIGITS>
    private_cdn:    <True|False>
    signature_algorithm:	<sha1|sha256>
    ```

### Troubleshooting installation on managed Windows machines

If you're on a corporate, school, or managed Windows machine, your system administrator may have applied restrictions that prevent the CLI from working. The CLI requires:

* Permission to install Python packages via `pip`
* Permission to execute `.exe` files
* Ability to modify or extend the `PATH` environment variable

In restricted environments, you may encounter errors such as:

* `pip install` fails with "Access is denied"
* `cld.exe` is blocked by antivirus software or execution policy
* `PATH` changes are not permitted or do not persist

If you encounter these issues, contact your system administrator. If the necessary permissions cannot be granted, the Cloudinary CLI is not supported in that environment.

> **TIP**:
>
> The Cloudinary CLI is optional. If your environment does not support Python, `pip`, or executable files, you can fully use Cloudinary without it:

> * **SDKs**: Use one of the [Cloudinary backend SDKs](cloudinary_sdks#backend_sdks) (Python, Node.js, Java, PHP, Ruby, and more) to interact with Cloudinary programmatically.

> * **REST APIs**: Call the [Upload API](image_upload_api_reference) or [Admin API](admin_api) directly using any HTTP client, including curl.

> * **Upload Widget**: Use the [Upload Widget](upload_widget) to upload assets directly from a browser with no local installation required.

### Setting configuration parameters

You can set any of the [configuration parameters](cloudinary_sdks#configuration_parameters) by appending them to your `CLOUDINARY_URL` environment variable as a query string, either when setting up your [default configuration](#installation_and_configuration) or when setting up alternative configurations using the [config](#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:

```
export CLOUDINARY_URL='cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name?upload_prefix=https://api-eu.cloudinary.com&cname=domain_name.com'
```

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

```
cloud_name:     cloud_name
api_key:        123456789012345
api_secret:     ***************xyzA
private_cdn:    False
signature_algorithm:	sha1
upload_prefix:	https://api-eu.cloudinary.com
cname:	        domain_name.com
```

### Upgrade

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

```
pip3 install --upgrade cloudinary-cli
```

## Basic commands

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

For a list of commands, enter:

```
cld --help
```

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

```
cld --version
```

To see the available Admin API methods, enter:

```
cld admin 
```

To see the available upload API methods, enter:

```
cld uploader
```

To show the usage for the search API, enter:

```
cld search --help  
```

To see the available utility methods, enter:

```
cld utils
```

See the [Command overview](#command_overview) for a listing of all available commands, or the [Command reference](#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 This tutorial presents the following topics. Click a timestamp to jump to that part of the video.
### Check if Python is installed

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=0 :sec=06 :player=cld} | To use the Cloudinary CLI, you need Python 3.6 or later. You can install Python from [https://www.python.org](https://www.python.org/). The Python Package Installer (`pip`) is installed with it.|

### Install the Cloudinary CLI package
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=0 :sec=10 :player=cld} | To install the Cloudinary CLI, run: <code>pip3 install cloudinary-cli|

### Set up your environment variable
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=0 :sec=25 :player=cld} | To make all your `cld` commands point to your Cloudinary product environment, set up your `CLOUDINARY_URL` environment variable. Obtain your environment variable from the [API Keys](https://console.cloudinary.com/app/settings/api-keys) page of the Cloudinary Console Settings.On Mac or Linux:<code>export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_nameOn Windows:<code>set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name |

### Check the configuration
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=0 :sec=54 :player=cld} | To check the configuration, run: <code>cld config|

### Run the help command
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=04 :player=cld} | For a list of commands, enter: <code>cld --help|

### Run the admin command
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=09 :player=cld} | To see the available Admin API methods, enter: <code>cld admin|

### Run the uploader command
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=22 :player=cld} | To see the available upload API methods, enter: <code>cld uploader|

### Run the search command
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=31 :player=cld} | To show the usage for the search API, enter: <code>cld search --help|

### Upload a video
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=40 :player=cld} | Upload the video, CLI_setup.mp4, setting the public ID and folder options: <code>cld uploader upload CLI_setup.mp4 public_id=setup folder=cli_video|

### Watch the uploaded video
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=2 :sec=11 :player=cld} | Use the url command to open a video in a browser: <code>cld url -rt video -o cli_video/setup|

## Command overview

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

cld [cli options] [command] [command options] [method] [method parameters]

For example, the following command runs the [resources\_by\_moderation](admin_api#get_resources_in_moderation) method in the [Admin API](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](perception_point_malware_detection_addon) anti-malware plugin, saving the output in a file called 'output.txt'.

```
cld -v ERROR admin --save output.txt -o max_results 40 -o resource_type raw resources_by_moderation perception_point rejected
```

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:

```
cld -v ERROR admin --save output.txt resources_by_moderation perception_point rejected -o max_results 40 -o resource_type raw 
```

or (using the syntax that assigns values):

```
cld -v ERROR admin --save output.txt resources_by_moderation perception_point rejected max_results=40 resource_type=raw 
```

> **NOTES**:
>
> * The methods available to the CLI, and their names, reflect those used in the [Python SDK](django_integration).

> * **If running on Windows**: for parameters that are specified as objects, you need to escape the double quotes within the curly braces using either `\` or `"`, for example, `\"text\"` or `""text""`.

### 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](#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](#admin)|Run methods from the Admin API.
[uploader](#uploader)|Run methods from the Upload API.
[search](#search)|Run the `search` method from the Admin API.
[provisioning](#provisioning)|Run methods from the Provisioning API.

#### File Management

COMMAND|DESCRIPTION
---|---
[migrate](#migrate)|Migrate a list of external media files, referenced as URLs with the same prefix, to Cloudinary.
[clone](#clone)|Clone assets from one product environment to another.
[sync](#sync)|Synchronize between a local folder and a Cloudinary folder.
[upload_dir](#upload_dir)|Upload a folder of assets and maintain the folder structure.
[regen_derived](#regen_derived)|Regenerate derived assets pertaining to a named transformation or transformation string.

#### Helpers

COMMAND|DESCRIPTION
---|---
[utils](#utils)|Run utility methods.
[make](#make)|Return template code for implementing the specified Cloudinary widget or functionality.
[url](#url)|Generate a Cloudinary URL.

#### Configuration

COMMAND|DESCRIPTION
---|---
[config](#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](admin_api) for details about each of the methods.

#### Syntax

cld [[cli options](#cli_options)] admin [[command options](#admin_command_options)] [[method](#admin_methods)] [[method parameters](#admin_methods)]

#### 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](admin_api) 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](admin_api) to see the parameters applicable to each method.

For example, the method [resources\_by\_tag](admin_api#get_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:

```
cld admin resources_by_tag animals -o max_results 10 -o resource_type video
```

> **TIP**: You can omit `admin` from the command when calling an Admin API method as long as you don't specify any options before the method.  So this also works:

```
cld resources_by_tag animals -o max_results 10 -o resource_type video
```

#### Examples

Show all the tags in your product environment.

```
cld admin tags
```

List all the resource types in a product environment: 

```
cld admin resource_types
```

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

```
cld admin create_transformation circle_face "c_thumb,w_250,h_250,g_face,r_max,q_auto"

cld admin create_upload_preset name=circle_face_on_upload transformation=circle_face
```

#### Writing output to a JSON file

You can redirect CLI output to a file using standard shell redirection. For example, to get all images and write them to a JSON file:

```
cld admin resources > result.json
```

To get the next page of results using the `next_cursor` value from the initial response, append to the same file using `>>`:

```
cld admin resources -o next_cursor "c0074444437a37f187982a8bebe87c92e8e1cd5a54af361ac6086c7a4c3d4148" >> result.json
```

> **TIP**:
>
> If you want to list assets within a specific folder:

> * In **fixed folder mode**, pass the folder path as a `prefix`, for example: `cld admin resources -o prefix "my_folder/" -o type "upload"` (this lists images by default; to list videos, additionally pass `-o resource_type "video"`)

> * In **dynamic folder mode**, use the `resources_by_asset_folder` method, for example: `cld admin resources_by_asset_folder "my_folder"` (this lists all assets, regardless of their resource type)
> Learn more about [folder modes](folder_modes).

---

### 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](image_upload_api_reference) for details about each of the methods.

#### Syntax

cld [[cli options](#cli_options)] uploader [[command options](#uploader_command_options)] [[method](#uploader_methods)] [[method parameters](#uploader_methods)]

#### 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](image_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](image_upload_api_reference) to see the parameters applicable to each method.

For example, the method [rename](image_upload_api_reference#rename_method) 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:

```
cld uploader rename photo1 photo2 -o to_type private -o invalidate true
```

> **TIP**: You can omit `uploader` from the command when calling an upload API method as long as you don't specify any options before the method.  So this also works:

```
cld rename photo1 photo2 -o to_type private -o invalidate true
```

#### 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.   

> **NOTE**: The tags "feathers" and "beak" are not needed to create the animated image, but are included as an example of applying more than one tag.

```
#!/bin/bash

for image in *.jpg
do
   cld uploader upload "$image" folder="birds" tags="bird,feathers,beak"   
done

cld uploader multi tag="bird" delay=1300
```

The result is a slide show of the bird images:

![Bird slide show](https://res.cloudinary.com/demo/image/upload/w_500/docs/CLI/bird.gif "with_url: false, with_code: false")

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

#### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.

#### Create an animated GIF with an image and a script
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliScript :min=0 :sec=20 :player=cld} | You can create an animated GIF that transforms the color saturation of an image. Begin with an image and a script.|

#### Create a script
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliScript :min=0 :sec=32 :player=cld} | In the script, increase the color saturation of an image and upload the image with the applied transformation.|

Here is the script:

```
#!/bin/bash

inc=10

# Increase the color saturation by 10 for each image
for ((sat = -100; sat <= 100; sat += 10))
do
      trans="transformation='{\"effect\": \"saturation:$sat\"}'"

      echo $trans

      # Upload the image with the applied transformation
      eval cld uploader upload umbrellas.jpg public_id="umbrellas_$inc" asset_folder="color" overwrite=true tags="umbrella" $trans

      ((inc++))
done

cld uploader multi tag="umbrella" delay=100
```

#### Run the script
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliScript :min=0 :sec=42 :player=cld} | Run the script to upload the image multiple times and increase the color saturation each time, giving each image a different public ID but the same tag.|

#### Apply a command to create the animation
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliScript :min=1 :sec=30 :player=cld} | Use the `multi` command to create the animation:<code>cld uploader multi tag="umbrella" delay=100|

#### View your animated GIF
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliScript :min=1 :sec=46 :player=cld} | Copy and paste the generated URL to view your animated GIF.|

And here are some additional upload API methods used to generate images from the pages of a PDF. The video also demonstrates how to generate a sprite from those images, but note that this feature will soon be deprecated.
> **INFO**:
>
> The **Sprite** feature will be deprecated as of **September 16, 2025**, and will no longer function after that date. Be sure to remove it from any production code.

#### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.

#### Begin with a multi-page PDF.
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=0 :sec=16 :player=cld} | Choose a multi-page PDF from your files.<code>blue_signs.pdf|

#### Upload the PDF to Cloudinary
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=0 :sec=25 :player=cld} | Use the upload command to upload the PDF, specifying its public ID.<code>cld uploader upload blue_signs.pdf public_id=blue_signs|

#### Use the explode method to pre-generate each page image
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=0 :sec=36 :player=cld} | Use the explode method to pre-generate images from each page of the PDF. Although not strictly necessary in this context, it does help to speed up the subsequent commands that need the derived images.<code>cld uploader explode blue_signs page=all|

#### Upload an image for each page and apply tags
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=0 :sec=41 :player=cld} | Use the upload command to upload the images derived from each page of the PDF as new images, and apply the tag **blue_signs** to each.<code>cld uploader upload http://res.cloudinary.com/carl/image/upload/pg_1/blue_signs.png tags=blue_signs|

#### View each new image
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=1 :sec=06 :player=cld} | Each image has a random public ID. Copy and paste the url to view the image.|

#### Find assets with the tag 'blue_signs'
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=1 :sec=16 :player=cld} | List the assets with the **blue_signs** tag to check that no other assets have the same tag, otherwise they would also be included in the sprite.<code>cld admin resources_by_tag blue_signs tags=true|

#### Generate a sprite from all images with the tag 'blue_signs'
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=1 :sec=32 :player=cld} | Use the CLI command to generate the sprite from the tagged images, and apply a transformation to crop each image to a square.<code>cld uploader generate_sprite blue_signs transformation='{"width"=200, "height":200, "crop": "fill", "gravity":"auto"}'|

#### View the sprite
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=1 :sec=48 :player=cld} | Copy and paste the `secure_image_url` into your browser.|

#### View the CSS
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=1 :sec=57 :player=cld} | Copy and paste the `secure_css_url` into your browser.|

#### Use the sprite and CSS in a web page
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliSprite :min=2 :sec=03 :player=cld} | Use the CSS classes to display images from your sprite in a web page.|

---

### 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](search_method) documentation for more details.

#### Syntax

cld [[cli options](#cli_options)] search [[command options](#search_command_options)] [[expression](#expression)]

#### 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](search_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:

> **NOTE**: The expression is encapsulated in double quotes to prevent the `>` character being interpreted as a redirection command.

```
cld search -f tags -n 30 -s public_id asc "resource_type:image AND tags=bird AND uploaded_at>1d AND bytes>100k"
```

Sample output:

```
{
  "total_count": 4,
  "time": 110,
  "resources": [
    {
      "public_id": "birds/ndnqgfjucvqt0aagrv0d",
      "display_name": "eagle",
      "asset_folder": "birds",
      "filename": "ndnqgfjucvqt0aagrv0d",
      "format": "jpg",
      "version": 1572953308,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2019-11-05T11:28:28+00:00",
      "uploaded_at": "2019-11-05T11:28:28+00:00",
      "bytes": 233593,
      "backup_bytes": 0,
      "width": 1920,
      "height": 1265,
      "aspect_ratio": 1.51779,
      "pixels": 2428800,
      "tags": [
        "bird",
        "feathers",
        "beak"
      ],
      "url": "http://res.cloudinary.com/cloud_name/image/upload/v1572953308/birds/ndnqgfjucvqt0aagrv0d.jpg",
      "secure_url": "https://res.cloudinary.com/cloud_name/image/upload/v1572953308/birds/ndnqgfjucvqt0aagrv0d.jpg",
      "status": "active",
      "access_mode": "public",
      "access_control": null,
      "etag": "c03d613e7e96c317d1db3dab0544ce07"
    },
    {
      "public_id": "birds/pa6o8xvvbg22dceytes0",
      "display_name": "hawk",
      "asset_folder": "birds",
      "filename": "pa6o8xvvbg22dceytes0",
      "format": "jpg",
      "version": 1572953306,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2019-11-05T11:28:26+00:00",
      "uploaded_at": "2019-11-05T11:28:26+00:00",
      "bytes": 420735,
      "backup_bytes": 0,
      "width": 1920,
      "height": 1277,
      "aspect_ratio": 1.50352,
      "pixels": 2451840,
      "tags": [
        "bird",
        "feathers",
        "beak"
      ],
      "url": "http://res.cloudinary.com/cloud_name/image/upload/v1572953306/birds/pa6o8xvvbg22dceytes0.jpg",
      "secure_url": "https://res.cloudinary.com/cloud_name/image/upload/v1572953306/birds/pa6o8xvvbg22dceytes0.jpg",
      "status": "active",
      "access_mode": "public",
      "access_control": null,
      "etag": "c6acb28c097000ddc4674965d2ee30d3"
    },
    {
      "public_id": "birds/rjgx7odwsqj8v6r3hxpr",
      "display_name": "robin",
      "asset_folder": "birds",
      "filename": "rjgx7odwsqj8v6r3hxpr",
      "format": "jpg",
      "version": 1572953304,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2019-11-05T11:28:24+00:00",
      "uploaded_at": "2019-11-05T11:28:24+00:00",
      "bytes": 420892,
      "backup_bytes": 0,
      "width": 1920,
      "height": 1280,
      "aspect_ratio": 1.5,
      "pixels": 2457600,
      "tags": [
        "bird",
        "feathers",
        "beak"
      ],
      "url": "http://res.cloudinary.com/cloud_name/image/upload/v1572953304/birds/rjgx7odwsqj8v6r3hxpr.jpg",
      "secure_url": "https://res.cloudinary.com/cloud_name/image/upload/v1572953304/birds/rjgx7odwsqj8v6r3hxpr.jpg",
      "status": "active",
      "access_mode": "public",
      "access_control": null,
      "etag": "284e8a1e18f013ab644b00be32003fed"
    },
    {
      "public_id": "birds/tkdkwjlvuj4wwpnjnzww",
      "display_name": "eagle",
      "asset_folder": "birds",
      "filename": "tkdkwjlvuj4wwpnjnzww",
      "format": "jpg",
      "version": 1572953310,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2019-11-05T11:28:30+00:00",
      "uploaded_at": "2019-11-05T11:28:30+00:00",
      "bytes": 365870,
      "backup_bytes": 0,
      "width": 1920,
      "height": 1280,
      "aspect_ratio": 1.5,
      "pixels": 2457600,
      "tags": [
        "beak",
        "bird",
        "feathers"
      ],
      "url": "http://res.cloudinary.com/cloud_name/image/upload/v1572953310/birds/tkdkwjlvuj4wwpnjnzww.jpg",
      "secure_url": "https://res.cloudinary.com/cloud_name/image/upload/v1572953310/birds/tkdkwjlvuj4wwpnjnzww.jpg",
      "status": "active",
      "access_mode": "public",
      "access_control": null,
      "etag": "534b82b763b375a47169bcb5b2cceabc"
    }
  ]
}
```

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

```
cld search -f tags -ff public_id,tags -n 30 -s public_id asc "resource_type:image AND tags=bird AND uploaded_at>1d AND bytes>100k"
```

Sample output:

```
{
  "total_count": 4,
  "time": 177,
  "resources": [
    {
      "public_id": "birds/ndnqgfjucvqt0aagrv0d",
      "tags": [
        "beak",
        "bird",
        "feathers"
      ]
    },
    {
      "public_id": "birds/pa6o8xvvbg22dceytes0",
      "tags": [
        "beak",
        "bird",
        "feathers"
      ]
    },
    {
      "public_id": "birds/rjgx7odwsqj8v6r3hxpr",
      "tags": [
        "beak",
        "bird",
        "feathers"
      ]
    },
    {
      "public_id": "birds/tkdkwjlvuj4wwpnjnzww",
      "tags": [
        "beak",
        "bird",
        "feathers"
      ]
    }
  ]
}
```

---

### 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](https://cloudinary.com/pricing#pricing-enterprise) plan upon [request](https://cloudinary.com/contact?plan=enterprise).

See the [Provisioning API reference](provisioning_api) 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 `<ACCOUNT_API_KEY>:<ACCOUNT_API_SECRET>@<ACCOUNT_ID>`. To set a temporary environment variable, for example:
    
    
    On Mac or Linux:

    ```
    export CLOUDINARY_ACCOUNT_URL=account://1234567890abcdef1234567890abcd:XYzPRB1Q8QP3ijBM2ipU5GeMHWk@1234abcd-1234-123a-1a2b-12345678901a
    ```

    
    
    On Windows (Command Prompt):

    ```
    set CLOUDINARY_ACCOUNT_URL=account://1234567890abcdef1234567890abcd:XYzPRB1Q8QP3ijBM2ipU5GeMHWk@1234abcd-1234-123a-1a2b-12345678901a
    ```

    
    
    On Windows (PowerShell):

    ```
    $Env:CLOUDINARY_ACCOUNT_URL="account://1234567890abcdef1234567890abcd:XYzPRB1Q8QP3ijBM2ipU5GeMHWk@1234abcd-1234-123a-1a2b-12345678901a"
    ```

    
    
    > **NOTE**:
>
> **Account API keys** were previously referred to as **provisioning API keys**.
    > **TIP**:
>
> You can copy and paste the component parts of your **CLOUDINARY_ACCOUNT_URL** from the **Account API Keys** page in the [Cloudinary Console Settings](https://console.cloudinary.com/app/settings/account). If your account is not set up for provisioning (available [upon request](https://cloudinary.com/contact?plan=enterprise) for [Enterprise](https://cloudinary.com/pricing#pricing-enterprise) plans), you won't see this section.

#### Syntax

cld [[cli options](#cli_options)] provisioning [[command options](#provisioning_command_options)] [[method](#provisioning_methods)] [[method parameters](#provisioning_methods)]

#### 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](provisioning_api) 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](provisioning_api) to see the parameters applicable to each method.

For example, the method, [update_user](provisioning_api#tag/users/), has one required parameter, `user_id`, and various optional parameters. To update the role of a user with id `7f08f1f1fc910bf1f25274aef11d27` to `admin`, enter:

```
cld provisioning update_user "7f08f1f1fc910bf1f25274aef11d27" -o role "admin"
```

#### Examples

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

```
cld provisioning create_sub_account docs-demo cloud_name=docs-demo-cloud base_account=0918b03ea306482e4858ee1ac2e7c8
```

Sample response:

```json
{
  "id": "7ad7f4e93ba3f349ee63642fb68e42",
  "name": "docs-demo",
  "description": null,
  "cloud_name": "docs-demo-cloud",
  "api_access_keys": [
    {
      "key": "123456789012345",
      "secret": "LbZYhvmGyklH5rF1iHUfOpMugew",
      "enabled": true
    }
  ],
  "enabled": true,
  "created_at": "2020-09-03T13:09:59Z",
  "custom_attributes": null
}
```

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`:

```
cld provisioning create_user "John Smith" "johnsmith@example.com" "media_library_user" sub_account_ids=0918b03ea306482e4858ee1ac2e7c8,7ad7f4e93ba3f349ee63642fb68e42

```

Sample response:

```json
{
  "id": "6a40b071a86d040ddf37f2dfb736fd",
  "name": "John Smith",
  "role": "media_library_user",
  "email": "johnsmith@example.com",
  "pending": true,
  "enabled": true,
  "created_at": "2020-09-08T10:06:14Z",
  "all_sub_accounts": false,
  "groups": [],
  "sub_account_ids": "0918b03ea306482e4858ee1ac2e7c8,7ad7f4e93ba3f349ee63642fb68e42"
}
```

---

### 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

cld [[cli options](#cli_options)] migrate [[command options](#migrate_command_options)] [upload_mapping](#upload_mapping) [file](#file)

#### 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](fetch_remote_images#configuring_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](fetch_remote_images#configuring_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](fetch_remote_images#configuring_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:

```
cld admin create_upload_mapping "remote_media" template="https://upload.wikimedia.org/wikipedia/commons/"
```

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:

```
cld migrate -v -d ";" remote_media url_file.txt
```

Sample verbose output:

```
Uploaded http://res.cloudinary.com/cloud_name/image/upload/v1/remote_media/c/cb/Eden_Gardens_under_floodlights_during_a_match.jpg
Uploaded http://res.cloudinary.com/cloud_name/image/upload/v1/remote_media/d/dc/Historical_cricket_bat_art.jpg
Uploaded http://res.cloudinary.com/cloud_name/image/upload/v1/remote_media/a/ae/Olympic_flag.jpg
Uploaded http://res.cloudinary.com/cloud_name/image/upload/v1/remote_media/3/35/Olympic-flag-Victoria.jpg
```

---

### clone

Use the `clone` command to copy assets from one product environment to another. You can optionally include tags and context with the assets.

The source product environment is the one you've configured for the CLI. You can specify a different source product environment using the `-c` or `-C` [options](#cli_options).

> **NOTES**:
>
> * The `clone` command currently doesn't support cloning structured metadata.

> * If you're cloning restricted assets, a private download URL is generated which may incur additional bandwidth costs. To avoid these additional costs, you can [configure](#setting_configuration_parameters) an `auth_key` in your configuration:`CLOUDINARY_URL="cloudinary://<api_key>:<api_secret>@<cloud_name>?auth_token[duration]=<duration>&auth_token[key]=<key>"`The `duration` set in this configuration is for [token-based access](control_access_to_media#token_based_access_premium_feature) and ignored by the clone command.  When cloning restricted assets with an `auth_key` configured, URLs expire after 3600 seconds by default. You can change this with the `-ue` option, but we advise against setting it to less than 3600 seconds. For information on obtaining an encryption key, see [Token-based access (premium feature)](control_access_to_media#token_based_access_premium_feature).

#### Syntax

cld [[cli options](#cli_options)] clone [[command options](#clone_command_options)] [target\_environment](#target_environment)

#### Command options

OPTION | DESCRIPTION
---|---
  -F, --force|Skip confirmation prompts (shown when there are over 500 assets to clone).
  -ow, --overwrite|Whether to overwrite existing files.
  -w, --concurrent_workers (integer)|Specify the number of concurrent network threads. Default: 30.
  -fi, --fields (field) (`tags`,`context`)|Specify whether to copy tags and context.
  -se, --search_exp (expression)|Define a search expression to filter the assets to clone.
  --async |Clone the assets asynchronously.
  -nu, --notification_url|Specify a URL to receive a webhook notification when cloning is complete.
  -ue, --url_expiry (integer)|The URL expiration duration in seconds. Only relevant if cloning restricted assets with an `auth_key` configured. If you don't provide an `auth_key`, a private download URL is generated which may incur additional bandwidth costs. Default: 3600.
  --help|Show help.

#### target\_environment

The product environment that you want to clone the assets to. You can specify a `CLOUDINARY_URL` environment variable or a [saved config](#config).

#### Examples

Copy all assets including tags and context to the product environment specified by its `CLOUDINARY URL` environment variable:

```
cld clone cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name -fi tags,context
```

Copy all assets with the tag, "animals", to the product environment specified by the saved config, "my_config":

```
cld clone my_config -se "tags:animals"
```

---

### sync

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

> **NOTES**:
>
> * **If your product environment uses [dynamic folders](folder_modes)**: 

>     * Syncing, in either direction, is based on display names and asset folders. When pushing, the display names of the uploaded assets are set to the filenames of the local assets (regardless of any upload preset settings). The local folder structure is replicated in Cloudinary as the asset folder structure. Likewise, when pulling, the filepaths and filenames of the local files are compared with the asset folder and display names of the assets in Cloudinary. Duplicate display names in an asset folder are resolved by adding incremental indices to create unique filenames when pulled to the local folder. The display names are not changed in Cloudinary, and the incremental indices are ignored when syncing back.

>     * The public ID values of the uploaded assets are set according to the options in your default API upload presets or any optional parameters specified in the `sync` call (which override the default upload presets). 

>     * If you specify `overwrite=true` together with `use_filename=true` and `unique_filename=false` (or your default API upload preset uses those settings), any existing asset in your product environment with a public ID identical to the filename of an asset in your local folder will effectively be deleted from its current asset folder and written to the new asset folder as per the sync.  This is because the public ID must be unique across the whole of the product environment. Similarly, if the directory that you're uploading has files with the same name in different sub-folders, and you're using the above three upload parameters, only the last one to be uploaded will be present in Cloudinary.

> * **If your product environment uses the legacy fixed folder mode**:

>     * Syncing, in either direction, is based on public IDs. When pushing, the public IDs of the uploaded assets are set to the filepaths and filenames of the local assets (regardless of any upload preset settings). When pulling, the local folder is compared with the full public ID path of the assets in Cloudinary.

>     * In fixed folder mode, because the folder structure is part of the public ID (based on forward slashes), you can have more than one file with the same name in different sub-folders of the directory you're syncing.

#### Syntax

cld [[cli options](#cli_options)] sync [[command options](#sync_command_options)] [local\_folder](#sync_local_folder) [cloudinary\_folder](#cloudinary_folder)

#### 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](image_upload_api_reference#upload_optional_parameters) to pass as a raw string.
  -O, --optional\_parameter\_parsed (param)|An [optional upload parameter](image_upload_api_reference#upload_optional_parameters) 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.

```
cld sync --push my_images my_cld_images/my_images
```

Sample output:

```
Found 7 items in local folder 'my_images'
Found 0 items in Cloudinary folder 'my_cld_images/my_images'
Uploading 7 items to Cloudinary folder 'my_cld_images/my_images'
Successfully uploaded /Users/me/my_images/hummingbird.jpg as my_cld_images/my_images/hummingbird
Successfully uploaded /Users/me/my_images/jay.jpg as my_cld_images/my_images/jay
Successfully uploaded /Users/me/my_images/bird.jpg as my_cld_images/my_images/bird
Successfully uploaded /Users/me/my_images/kingfisher.jpg as my_cld_images/my_images/kingfisher
Successfully uploaded /Users/me/my_images/ara.jpg as my_cld_images/my_images/ara
Successfully uploaded /Users/me/my_images/parrot.jpg as my_cld_images/my_images/parrot
Successfully uploaded /Users/me/my_images/swan.jpg as my_cld_images/my_images/swan
Done!
```

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:

```
cld sync -F --pull my_images my_cld_images/my_images
```

Sample output:

```
Found 7 items in local folder 'my_images'
Found 5 items in Cloudinary folder 'my_cld_images/my_images'
Skipping 5 items
Deleting 2 local files...
Deleted '/Users/me/my_images/swan.jpg'
Deleted '/Users/me/my_images/kingfisher.jpg'
Deleting empty folders...
Downloading 0 files from Cloudinary
Done!
```

---

### upload_dir

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

> **NOTES**:
>
> * **If your product environment uses [dynamic folders](folder_modes)**: 

>     * The display names of the uploaded assets are set to the filenames of the local assets (regardless of any upload preset settings). The local folder structure is replicated in Cloudinary as the asset folder structure. 

>     * The public ID values of the uploaded assets are set according to the options in your default API upload presets, the upload preset specified together with the `upload_dir` command, or any optional parameters specified in the `upload_dir` call (which override any upload presets). 

>     * If you specify `overwrite=true` together with `use_filename=true` and `unique_filename=false` (or either your default API upload preset or specified upload preset uses those settings), any existing asset in your product environment with a public ID identical to the filename of an asset in your local folder will effectively be deleted from its current asset folder and written to the new asset folder as per the upload.  This is because the public ID must be unique across the whole of the product environment. Similarly, if the directory that you're uploading has files with the same name in different sub-folders, and you're using the above three upload parameters, only the last one to be uploaded will be present in Cloudinary.

> * **If your product environment uses the legacy fixed folder mode**:

>     * The public IDs of the uploaded assets are set to the filepaths and filenames of the local assets (regardless of any upload preset settings). 

>     * In fixed folder mode, because the folder structure is part of the public ID (based on forward slashes), you can have more than one file with the same name in different sub-folders of the directory you're uploading.

#### Syntax

cld [[cli options](#cli_options)] upload\_dir [[command options](#upload_dir_command_options)] [[local\_folder](#dir_local_folder)]

#### 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](image_upload_api_reference#upload_optional_parameters) to pass as a raw string.
-O, --optional\_parameter\_parsed (param)|An [optional upload parameter](image_upload_api_reference#upload_optional_parameters) 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](upload_presets) 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.

```
cld upload_dir -f my_images_on_cloudinary -o overwrite true my_images
```

This results in the following folder structure in Cloudinary:
<pre>
    Home
    +--my\_images\_on\_cloudinary
    |  +-- my\_images
    |  |   +-- \

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

```
cld upload_dir -e -f my_images_on_cloudinary -o overwrite true my_images
```

This results in the following folder structure in Cloudinary:
<pre>
    Home
    +--my\_images\_on\_cloudinary
    |  +-- \

This video shows the `upload_dir` command in action:

#### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.

#### Remove the image backgrounds during upload to Cloudinary
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliDir :min=0 :sec=05 :player=cld} |Using an upload preset, you can transform your images during upload to Cloudinary.|

#### Create an upload preset with the CLI to remove background images
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliDir :min=0 :sec=13 :player=cld} |Use the `create_upload_preset` command to create an upload preset that invokes Cloudinary AI background removal (`background_removal=cloudinary_ai`). The upload preset also uses the original filename as the public ID (`use_filename=true unique_filename=false`) and ensures an existing file with the same public ID isn't overwritten (`overwrite=false`).<code>cld admin create_upload_preset name=remove_background overwrite=false use_filename=true unique_filename=false type=upload access_mode=public background_removal=cloudinary_ai|

#### Upload the images to Cloudinary
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliDir :min=0 :sec=41 :player=cld} | Use the `upload_dir` command to upload the images with the newly created upload preset.<code>cld upload_dir -f new_toys -p remove_background soft_toys|

#### View the new folder in the Media Library
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=cliDir :min=0 :sec=52 :player=cld} | The new folder contains the uploaded images without backgrounds.|

---

### regen_derived

Use the `regen_derived` command to regenerate all derived assets created using a specific named transformation or transformation string. For example, you may want to use this after updating a named transformation definition in order to invalidate the existing derived assets and repopulate the cache with up-to-date versions of the assets.

#### Syntax

cld [[cli options](#cli_options)] regen\_derived [[command options](#regen_derived_command_options)] [[transformation\_name](#transformation_name)]

#### 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](image_transformations#named_transformations), for example, `black-border`, or a transformation string, for example `t_black-border/a_50/l_icon/fl_layer_apply,g_west`.

{notes}

* You can find all existing transformation strings in the [Transformation Log](https://console.cloudinary.com/app/image/manage/log) in the Console. 
* These may not correspond directly to a transformation used in a URL, for example if `f_auto` is used in the requesting URL, this will be changed to the actual format delivered, for example, `f_avif`.
* If a transformation has been requested without an extension, append a forward slash to the end of the transformation string, for example, `t_small-square/f_avif/a_30/`.
  
{/note}

#### 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.

```
cld regen_derived 'small-square' -F -A -ea -enu 'https://mysite.example.com/my_notification_endpoint'
```

Sample response:

```
Regenerating 2 derived asset(s) with eager_async=True...
Processing https://res.cloudinary.com/demo/image/upload/t_small-square/v1695889160/cld-sample.jpg
Processing https://res.cloudinary.com/demo/image/upload/t_small-square/v1695898027/docs/luggage.jpg
Regeneration in progress. It may take up to 10 mins to see the changes. Please contact support if you still see the old media.
```

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.

```
cld regen_derived 't_small-square/f_avif,fl_aavif/a_30/jpg' -F -A
```

Sample response:

```
Regenerating 3 derived asset(s)...
Regenerated https://res.cloudinary.com/demo/image/upload/t_small-square/f_avif,fl_aavif/a_30/v1690196527/docs/garden-gnome.jpg
Regenerated https://res.cloudinary.com/demo/image/upload/t_small-square/f_avif,fl_aavif/a_30/v1691056801/docs/men-laughing.jpg
Regenerated https://res.cloudinary.com/demo/image/upload/t_small-square/f_avif,fl_aavif/a_30/v1690537544/docs/ladies-smiling.jpg
Regeneration complete. It may take up to 10 mins to see the changes. Please contact support if you still see the old media.
```

---

### utils

The `utils` command enables you to run Cloudinary utility methods.

#### Syntax

cld [[cli options](#cli_options)] utils [[command options](#utils_command_options)] [[method](#utils_methods)] [[method parameters](#utils_methods)]

#### 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](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L589) | [Using Cloudinary backend SDKs to generate SHA authentication signatures](authentication_signatures#using_cloudinary_backend_sdks_to_generate_sha_authentication_signatures)
[cloudinary_url](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L714) | [Embedding images in web pages using SDKs](image_transformations#embedding_images_in_web_pages_using_sdks)
[download_archive_url](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L924) | [download_archive_url syntax](image_upload_api_reference#download_archive_syntax)
[download_backedup_asset](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L950) | [download_backup method](image_upload_api_reference#download_backup_method)
[download_folder](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L934) | [download_folder syntax](image_upload_api_reference#download_folder_syntax)
[download_zip_url](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L928) | [download_zip_url syntax](image_upload_api_reference#download_zip_url_syntax) 
[private_download_url](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L891) | [Providing time-limited access to private media assets](control_access_to_media#providing_time_limited_access_to_private_media_assets)
[verify_api_response_signature](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L1463) | [Verifying signatures in the JSON response](response_signatures)
[verify_notification_signature](https://github.com/cloudinary/pycloudinary/blob/b18617d8632c736f49644fbb7b38b6e3d56bee2a/cloudinary/utils.py#L1488) | [Verifying notification signatures](notification_signatures)

#### Examples

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

```
cld utils api_sign_request '{"timestamp": 1595793040, "public_id": "flower"}' 323127161127519
```
> **NOTE**: If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either `\` or `"`, for example, `\"text\"` or `""text""`.
Sample output:

```
a1983942190b20a6b40849751032022914c25bd3
```

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

```
cld utils cloudinary_url sample width=300 height=100 crop=scale
```

Sample output:

```
http://res.cloudinary.com/demo/image/upload/c_scale,h_100,w_300/sample
```

---

### make

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

#### Syntax

cld [[cli options](#cli_options)] make [[command options](#make_command_options)] [[language](#language)] [[template](#template)]

#### 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](media_library_widget).
product\_gallery | Return template code for the [Product Gallery](product_gallery).
upload\_widget | Return template code for the [Upload Widget](upload_widget).
video\_player | Return template code for the [Video Player](cloudinary_video_player).

#### Examples

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

```
cld make upload_widget
```

Sample output:

```
<button id="upload_widget" class="cloudinary-button">Upload files</button>

<script src="https://widget.cloudinary.com/v2.0/global/all.js" type="text/javascript"></script>  

<script type="text/javascript">  

    var myWidget = cloudinary.createUploadWidget({
        cloudName: 'cloud_name',
        upload_preset: 'preset1',
        }, (error, result) => { if (result.event == "success") {
            console.log(result.info) // result.info contains data from upload
        } })

        document.getElementById("upload_widget").addEventListener("click", function(){
            myWidget.open();
        }, false);
    
</script>
```

Generate sample Python code for finding all empty folders.

```
cld make python find_all_empty_folders
```

Sample output:

```
import cloudinary

cloudinary.config(**{
    "cloud_name": "cloud_name",
    "api_key": "123456789012345",
    "api_secret": "abcde"
})


from cloudinary import api

def find_end(root, f):
    root = root.replace(" " , "%20")
    res = list(filter(lambda x: x != 'search', list(map(lambda x: x['path'], api.subfolders(root)['folders']))))
    tmp = [find_end(i, f) for i in res] if res != [] else f.append(root)
    if root == "": return f

empty = list(filter(lambda x: cloudinary.Search().expression("folder:{}".format(x)).execute()['total_count'] == 0, find_end("", [])))

print("Empty folders:\n{}".format(empty))
```

---

### url

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

> **NOTE**: Unless the URL is opened, the derived asset is not generated.

#### Syntax

cld [[cli options](#cli_options)] url [[command options](#url_command_options)] public_id [[transformation](#transformation)]

#### Command options

OPTION | DESCRIPTION
---|---
-rt, --resource\_type [image, video, raw] | The asset type.
-t, --type [upload, private, authenticated, fetch, list, url2png] | The [delivery type](image_transformations#delivery_types).
-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](transformation_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.

```
cld url -t upload -o docs/animals_on_road.jpg w_400,c_thumb,g_auto,e_vectorize:10:0.6/e_vignette:40
```

Sample output:

```
http://res.cloudinary.com/demo/image/upload/w_400,c_thumb,g_auto,e_vectorize:10:0.6/e_vignette:40/docs/animals_on_road.jpg
```

![Transformed animals_on_road](http://res.cloudinary.com/demo/image/upload/w_400,c_thumb,g_auto,e_vectorize:10:0.6/e_vignette:40/docs/animals_on_road.jpg "with_url: false, with_code: false")

Use the [URL2PNG](url2png_website_screenshots_addon) 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.

```
cld url -t url2png -o -s https://cloudinary.com w_300,h_250,g_north,c_fill,e_grayscale
```

Sample output:

```
http://res.cloudinary.com/cloud_name/image/url2png/s--6WjWrdiu--/w_300,h_250,g_north,c_fill,e_grayscale/https://cloudinary.com
```

![Cloudinary screenshot](http://res.cloudinary.com/demo/image/upload/docs/cloudinary_gs "with_url: false, with_code: false")

---

### 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](#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:

```
cld -c cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name admin usage
```

Whereas using the saved configuration "accountx":

```
cld -C accountx admin usage
```

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

**See also:** [Setting configuration parameters](#setting_configuration_parameters)

Creating a saved configuration may put your API secret at risk as it is stored in a local plain text file.

#### Syntax

cld config [[options](#config_options)]

#### 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.

> **TIP**: If you copy the examples below, replace the placeholders in the environment variable with real values, which you can obtain from the [API Keys](https://console.cloudinary.com/app/settings/api-keys) page of the Cloudinary Console Settings.

Display the current configuration.

```
cld config
```

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

```
cld config -n accountx cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name

cld config -s accountx

cld -C accountx admin upload_presets

cld config -rm accountx
```

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.

```
cld config -url cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name

cld -C cloud_name uploader upload "family.jpg" tags="mum,dad,grandpa,grandma" 
```

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

```
cld config -ls > configs.txt

while read in; do cld config -rm "$in"; done < configs.txt
```