> ## Documentation Index > This page is part of the Image and Video APIs product. Fetch the complete documentation index for Image and Video APIs at: https://cloudinary.com/documentation/llms-image-and-video-apis.txt?referrer=docpage and then use it to discover all relevant pages before exploring further. > If your task extends beyond this product, fetch the top-level index covering all Cloudinary products and topics at: https://cloudinary.com/documentation/llms.txt?referrer=docpage # 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 The Cloudinary CLI package is called `cloudinary-cli`. Installing it gives you the `cld` command (and a `cloudinary` alias). ### Install the CLI **Prerequisite**: The Cloudinary CLI requires Python 3.8 or later. If you don't already have a compatible version, you can: * Install Python from [https://www.python.org](https://www.python.org/). * Use the [uv](#uv) option below, which installs a compatible Python for you if needed. * Use the [Docker](#docker_option) option below, which doesn't require a local Python installation (it bundles its own Python and the CLI runs against that version inside the container). Choose the installation method that best fits your setup: #### pipx (recommended) [pipx](https://pipx.pypa.io) installs the CLI into an isolated environment and puts `cld` on your `PATH`, so it doesn't interfere with your other Python packages. ``` pipx install cloudinary-cli ``` If `cld` isn't found afterwards, run `pipx ensurepath` and open a new terminal. #### uv [uv](https://docs.astral.sh/uv/) installs the CLI as an isolated tool. It also installs a compatible Python for you if needed: ``` uv tool install cloudinary-cli ``` Or run any command without installing the CLI globally, e.g.: ``` uvx --from cloudinary-cli cld --help ``` #### pip If using this option, it's recommended to install it into a virtual environment to avoid conflicts with other packages: ``` python3 -m venv cloudinary-cli-env source cloudinary-cli-env/bin/activate pip install cloudinary-cli ``` Alternatively, install for the current user only: ``` python3 -m pip install --user cloudinary-cli ``` #### Docker (no local Python needed) Run the CLI from the official `cloudinary/cli` image, passing your `CLOUDINARY_URL` environment variable (if you don't have `CLOUDINARY_URL` set, see [Set a CLOUDINARY_URL environment variable](#set_a_cloudinary_url_environment_variable) for details of how to set it): ``` docker run --rm -e CLOUDINARY_URL cloudinary/cli config ``` #### Verify the installation Check the installed version: ``` cld --version ``` ### Configure your product environment To make all your `cld` commands point to your Cloudinary product environment, you can either [log in with OAuth](#log_in_with_oauth_recommended) (recommended) or set up a `CLOUDINARY_URL` environment variable. #### Log in with OAuth (recommended) Authenticate through your browser without copying any API keys. The CLI saves the session as a named configuration and refreshes the token automatically, so you stay logged in: ``` cld login ``` See the [login](#login) command reference for details. #### Set a CLOUDINARY_URL environment variable Use this when you need an explicit key and secret, for example in CI or shared scripts. The variable takes the form `:@`. For example, to set a temporary environment variable (replace the API key, secret, and cloud name with your own): * 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" ``` > **TIP**: > > :title=Tips > * 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 `` and `` with your actual values. Your cloud name is already correctly included in the format.* If you don't yet have a Cloudinary account, you can create one from the [web signup form](https://cloudinary.com/users/register_free). AI agents acting on a human's behalf can provision a Free-plan account with the [agent signup](#agent) command. Check your configuration by running: ``` cld config ``` A response in the following form is returned: ``` name: (api_key) [default, active] signature_version: 2 cloud_name: api_key: api_secret: **** private_cdn: False ``` You may choose 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. ##### 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 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: ``` name: cloud_name (api_key) [default, active] signature_version: 2 cloud_name: cloud_name api_key: 123456789012345 api_secret: ****xyzA private_cdn: False upload_prefix: https://api-eu.cloudinary.com cname: domain_name.com ``` ### Troubleshooting installation If the `cld` command isn't found after installation: * **pipx or uv**: The tool's scripts directory isn't on your `PATH`. Run `pipx ensurepath` (for pipx) or `uv tool update-shell` (for uv), then open a new terminal. * **pip user-specific (--user) install**: The user scripts directory isn't on your `PATH`. Find its location with `python3 -m site --user-base`. Scripts live in the `bin` subdirectory on Mac or Linux, and the `Scripts` subdirectory on Windows. Add that directory to your `PATH`. For example, on Mac or Linux: ``` export PATH="$PATH:$(python3 -m site --user-base)/bin" ``` * **Fallback**: You can always invoke the CLI through Python directly: ``` python3 -m cloudinary_cli.cli ``` ### 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 don't persist If you encounter these issues, contact your system administrator. If the necessary permissions can't be granted, the Cloudinary CLI isn't supported in that environment. > **TIP**: > > The Cloudinary CLI is optional. If your environment doesn't 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. ### Upgrade To upgrade your installation of the Cloudinary CLI to the latest version, use the command that matches how you installed it. pipx: ``` pipx upgrade cloudinary-cli ``` uv: ``` uv tool upgrade cloudinary-cli ``` pip: ``` pip 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}| | | --- | --- | | | 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}| | | --- | --- | | | To install the Cloudinary CLI, run: pip3 install cloudinary-cli| ### Set up your environment variable {table:class=tutorial-bullets}| | | --- | --- | | | 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:export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_nameOn Windows:set CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name | ### Check the configuration {table:class=tutorial-bullets}| | | --- | --- | | | To check the configuration, run: cld config| ### Run the help command {table:class=tutorial-bullets}| | | --- | --- | | | For a list of commands, enter: cld --help| ### Run the admin command {table:class=tutorial-bullets}| | | --- | --- | | | To see the available Admin API methods, enter: cld admin| ### Run the uploader command {table:class=tutorial-bullets}| | | --- | --- | | | To see the available upload API methods, enter: cld uploader| ### Run the search command {table:class=tutorial-bullets}| | | --- | --- | | | To show the usage for the search API, enter: cld search --help| ### Upload a video {table:class=tutorial-bullets}| | | --- | --- | | | Upload the video, CLI_setup.mp4, setting the public ID and folder options: cld uploader upload CLI_setup.mp4 public_id=setup folder=cli_video| ### Watch the uploaded video {table:class=tutorial-bullets}| | | --- | --- | | | Use the url command to open a video in a browser: 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 ---|--- [login](#login)|Log in to Cloudinary via OAuth (opens a browser) and save the session as a configuration. [logout](#logout)|Log out of a saved OAuth login and remove its configuration. [config](#config)|Manage product environment configurations. #### AI agents COMMAND|DESCRIPTION ---|--- [agent](#agent)|Commands for AI agents acting on behalf of a human, such as provisioning an account. ## 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}| | | --- | --- | | | 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}| | | --- | --- | | | 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}| | | --- | --- | | | 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}| | | --- | --- | | | Use the `multi` command to create the animation:cld uploader multi tag="umbrella" delay=100| #### View your animated GIF {table:class=tutorial-bullets}| | | --- | --- | | | Copy and paste the generated URL to view your animated GIF.| --- ### 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 `:@`. 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 management keys** were previously referred to as **account API keys** and **provisioning API keys**. > **TIP**: > > You can copy and paste the component parts of your **CLOUDINARY_ACCOUNT_URL** from the **Account Management Keys** page in the [Cloudinary Console Settings](https://console.cloudinary.com/app/settings/account). If your account isn't 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](migration#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](migration#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](migration#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 doesn't 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://:@?auth_token[duration]=&auth_token[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. > * **Syncing from Dropbox:** > * If your assets are stored in Dropbox, make sure you are using the **Dropbox Desktop application** and that the files are fully available on your local machine. > * The `cld sync` command only uploads files that physically exist in the local directory you specify. Files that are marked as online-only or not yet downloaded by the Dropbox client will not be synced to Cloudinary. #### 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! ``` --- #### Google Drive example If your assets are stored in Google Drive, first mirror the target Drive folder to your local machine (for example, using **Google Drive for desktop**) so the files exist on disk. Then run `cld sync` to push the local folder to a Cloudinary folder while preserving the folder structure: ```bash cld sync --push path/to/local_drive_folder path/in/cloudinary ``` This uploads all files and subfolders under `path/to/local_drive_folder` to the specified Cloudinary folder. > **NOTE**: If your assets are stored in Google Cloud Storage, consider using [auto-upload URL mapping](migration#configuring_auto_upload_url_mapping) for lazy migration instead of syncing from a local folder. ### 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 don't 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: 
    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:

    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}|  | 
| --- | --- |
| |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}|  | 
| --- | --- |
| |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`).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}|  | 
| --- | --- |
| | Use the `upload_dir` command to upload the images with the newly created upload preset.cld upload_dir -f new_toys -p remove_background soft_toys|

#### View the new folder in the Media Library
{table:class=tutorial-bullets}|  | 
| --- | --- |
| | 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](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

{code}
cld [[cli options](#cli_options)] utils [[command options](#utils_command_options)] [[method](#utils_methods)] [[method parameters](#utils_methods)]
{/code}

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

```


  


```

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 isn't 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_trans_flags_delivery_types#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")

---

### login

Logging in with OAuth lets you authenticate through your browser instead of copying an API key and secret into an environment variable. The CLI saves the session as a named configuration and refreshes the token automatically, so you stay logged in. Use it when you want a quick, secure setup on your own machine; use a `CLOUDINARY_URL` environment variable or a saved [config](#config) when you need an explicit key and secret (for example, in CI or shared scripts).

The `login` command logs in to Cloudinary via OAuth, opening a browser to complete authentication. The session is saved as a named configuration that you can select with the `-C` [option](#cli_options), exactly like any other [saved configuration](#config).

The first login or configuration becomes the [default](#default_vs_active_configuration) automatically. If other configurations already exist, the new login is saved, but isn't made the default. In this case, the CLI tells you so and provides the command to change yours to the default (`cld config -d `).

#### Syntax

cld [[cli options](#cli_options)] login [[name](#login_name)] [[options](#login_options)]

#### name
An optional name for the saved configuration. Defaults to the cloud name.

#### Options
OPTION | DESCRIPTION
---|---
--region (region)|The Cloudinary data center to log in to (for example, `eu`, `ap`, or `api-eu`). Defaults to the global region (`api`). **Note**: [Non-US data centers](admin_api#eu_or_ap_data_centers_and_endpoints_premium_feature) are available only for Enterprise accounts.
--set-default|Set this login as the [default](#default_vs_active_configuration) configuration, used when no `-c`/`-C` option and no `CLOUDINARY_URL` is given.
--help|Show help.

#### Examples

Log in and save the configuration under the cloud name:

```
cld login
```

Log in and save the configuration under a specific name:

```
cld login my-account
```

Log in to a specific region:

```
cld login --region eu
```

Log in and set this configuration as the default:

```
cld login --set-default
```

Sample output from a successful login:

```
Opening browser to log in to Cloudinary...
If it doesn't open automatically, visit:
https://oauth.cloudinary.com/oauth2/auth?client_id=...
Logged in. Saved as 'docs-login-test'.
This is now the default configuration. Run `cld ` to use it, or `cld -C docs-login-test ` to select it explicitly.
```

---

### logout

The `logout` command logs you out of a saved OAuth login. It revokes the login's token at the server and removes its saved configuration. Run it without a name to choose from a list of your saved OAuth logins.

#### Syntax

cld [[cli options](#cli_options)] logout [[name](#logout_name)]

#### name
**Optional**. The name of the saved OAuth login to log out of. With no name, the CLI lists your saved OAuth logins, if you have more than one, and prompts you to pick one.

> **NOTES**:
>
> * If the token can't be revoked (for example, you're offline), the saved configuration is still removed, and the CLI warns that the token may remain valid until it expires.

> * `logout` refuses to remove a non-OAuth configuration. To remove those, use `cld config -rm `.

#### Examples

Choose which saved OAuth login to log out of from a list (or confirm intention to log out, if only one saved login):

```
cld logout
```

Log out of a specific saved login:

```
cld logout my-account
```

Sample output:

```
Logged out of 'docs-login-test'. Its token was revoked and the saved login removed.
```

---

### agent

The `agent` command provides options for AI agents acting on behalf of a human user. 

#### agent signup

`cld agent signup` is for AI agents provisioning a Cloudinary account on a human's behalf. It creates a Free-plan account without requiring any existing configuration, sends a verification email to the human, and saves the returned credentials as a named configuration. The credentials are inert until the human completes the email verification.

> **NOTE**: If you're a human (or the human prefers to sign up themselves), use the [web signup form](https://cloudinary.com/users/register_free) instead.

#### Syntax

cld [[cli options](#cli_options)] agent signup [email](#agent_email) [agent_framework](#agent_arguments) [agent_llm_model](#agent_arguments) [agent_goal](#agent_arguments) [[options](#agent_options)]

#### email
The email address of the human on whose behalf the account is being provisioned. The verification email is sent to this address.

> **NOTE**: Every account must have a unique email address. Supply one that isn't already associated with an existing Cloudinary account.

#### agent_framework, agent_llm_model, agent_goal
Required positional arguments that identify the agent and its task: the agent framework, the LLM model the agent is using, and a short description of the agent's goal.

#### Options
OPTION | DESCRIPTION
---|---
--sdk-framework (name)|The Cloudinary SDK framework the agent intends to use.
--name (name)|Name for the saved configuration (default: the returned cloud name).
--set-default|Set the saved configuration as the [default](#default_vs_active_configuration).
--no-save|Show the credentials but don't save them as a configuration.
--json|Output the full raw JSON response (the agent contract) instead of the human summary.
--help|Show help.

> **NOTES**:
>
> * A verification email is sent to the supplied address, and the returned credentials are inert until the human completes the verification.

> * The credentials are printed before they're saved, so a save failure can't lose them.

> * The new product environment is saved as a named configuration (named after the cloud) so it's ready to use once activated. Select it with `cld -C  `.

> * This endpoint is rate-limited per IP address. If you hit the rate limit, the CLI tells you to wait and retry.

> * If you already signed up with the same email on this machine, the CLI stops before making any API call and points you at the existing saved configuration (`cld -C  `).

> * If an account already exists for that email but nothing is saved locally, the CLI explains how to add it (`cld config -n  `, or `cld login` for OAuth) and to complete the verification email if the account was newly created.

> * Configuration names wrapped in double underscores (for example, `__default__`) are reserved for internal use and rejected with `Error: Invalid value: '__default__' is a reserved configuration name.` (Plain names such as `default` are fine.)

#### Examples

Provision a Free-plan account and save the returned credentials:

```
cld agent signup you@example.com claude-code claude-fable-5 "test the agent account flow"
```

Provision an account and show the credentials without saving them:

```
cld agent signup you@example.com claude-code claude-fable-5 "test the agent account flow" --no-save
```

Provision an account, save it under a specific name, and make it the default:

```
cld agent signup you@example.com claude-code claude-fable-5 "test the agent account flow" --name my-agent --set-default
```

Sample output from a successful signup:

```
Cloudinary account created.
Email:          you@example.com
Plan:           free
Cloud name:     f3ddxzvf
API key:        169619536154115
CLOUDINARY_URL: cloudinary://169619536154115:...@f3ddxzvf
External id:    62993d91-29b3-472f-ae08-1a3d860f3e64

A verification email has been sent to the supplied email address. Guide the user to open the email and complete the verification process. ...

Config 'f3ddxzvf' saved!
Example usage: cld -C f3ddxzvf 
Default set to 'f3ddxzvf'. Run `cld ` to use it, or `cld -C f3ddxzvf ` to select it explicitly.
Note: the account's credentials are inert until the emailed verification is completed.
```

---

### 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's 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.
-d, --default (name)|Set the named saved configuration as the [default](#default_vs_active_configuration).
--set-default|With `-n`/`--from_url`, set the configuration created by this command as the [default](#default_vs_active_configuration).
-ud, --unset-default|Clear the stored default configuration.
-r, --refresh (name)|[Refresh the OAuth token](#manual_token_refresh) of a saved configuration (uses the active configuration if no name is given).
-ra, --refresh-all|[Refresh](#manual_token_refresh) every saved OAuth configuration whose token is stale.
-f, --force|With `--refresh`/`--refresh-all`, refresh even tokens that are still fresh.
-j, --json|Output as JSON (with `-ls`, `-s`, or the bare `config` view).
--help|Show help.

#### Default vs. active configuration
Two related concepts determine which product environment a command uses:

* The **default** configuration is used automatically when you don't pass a `-c`/`-C` [option](#cli_options) and no `CLOUDINARY_URL` environment variable is set.
* The **active** configuration is the one the current command actually resolves to.

The first configuration you create (whether by [logging in](#login) or by [creating one](#config) from an environment variable) becomes the default automatically. If other configurations already exist, a new one is saved but not made default. In that case, you can set it `cld config -d `.

To view your configurations:

* `cld config` (with no options) shows the currently **active** account.
* `cld config -ls` lists all saved configurations, marking which is the **default** and which is **active** with a `*`:

    ```
    NAME                        CLOUD                       TYPE     DEFAULT  ACTIVE
    sdk-test-cli-test-54670288  sdk-test-cli-test-54670288  api_key
    constantine-test            constantine-test            oauth
    eu-cloud                    eu-cloud                    oauth
    constantine-sdk             constantine-sdk             api_key  *        *
    ```

    The `TYPE` column can either be `api_key` for configurations created from an environment variable, or `oauth` for [OAuth logins](#login). An `EMAIL` column is also shown when a saved configuration carries an account email (for example, one created by [agent signup](#agent)).

* `cld config -s ` shows the details of a specific configuration. An OAuth configuration shows token and expiry fields instead of an API key and secret:

    ```
    name: my-test (oauth)

    signature_version: 2
    cloud_name:        my-test
    private_cdn:       False
    oauth_token:       ****wsig
    refresh_token:     ****_new
    issued_at:         1782726553 (2026-06-29 09:49:13 UTC)
    expires_at:        1782726853 (2026-06-29 09:54:13 UTC, expired)
    region:            api
    issuer:            https://oauth.cloudinary.com/
    upload_prefix:     https://api.cloudinary.com
    ```

> **NOTE**: API secrets and OAuth tokens are masked in the output, showing only the last few characters (for example, `api_secret: ****Bnt8` or `oauth_token: ****wsig`).

#### Resolution precedence

When a command needs to determine which account to use, it resolves the configuration in the following order, highest priority first:

1. `-c`: an inline `CLOUDINARY_URL`.
1. `-C`: a saved configuration name.
1. The stored [default](#default_vs_active_configuration) configuration.
1. The `CLOUDINARY_URL` environment variable.

#### Refreshing OAuth tokens
OAuth tokens are refreshed automatically, so you don't normally need to refresh them yourself. To refresh manually:

```
cld config --refresh 
cld config --refresh-all
```

Add `--force` to refresh tokens that are still fresh:

```
cld config --refresh docs-login-test --force
```

If a token can no longer be refreshed (for example, the login was revoked), the CLI reports which configuration is affected and provides the exact [cld login](#login) command to log in again.

#### Creating a configuration

When you create an API-key configuration with `-n`/`--new` or `-url`/`--from_url`, the CLI validates the credentials by pinging Cloudinary before saving. If the credentials are wrong, it shows an error such as `error: Failed to ping Cloudinary: Error 401 - ...` and doesn't save the configuration. A configuration is saved only after its credentials check out.

To create a configuration and make it the [default](#default_vs_active_configuration) in one step, add `--set-default`:

```
cld config -n  cloudinary://:@ --set-default
```

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