“Anything you can do, I can do better,
I can do anything better than you…” (Irving Berlin)
If the Cloudinary CLI could sing, this could well be its song. Virtually anything you can do with the Cloudinary upload and admin APIs, you can do with the CLI (Command Line Interface), and much of the functionality that’s available through your account console is also accessible through the CLI. As to being ‘better’, it probably depends on the context, but in many situations it’s certainly quicker and easier, and it provides some bonus functionality that isn’t available through the APIs or console.
Initiation
All you need to get started with the Cloudinary CLI is your own Cloudinary account (sign up for free if you don’t have one) and Python 3.6 or later. You can install the Cloudinary CLI using the Python Package installer (PIP), as follows:
To make all your cld commands point to your Cloudinary account, set up your CLOUDINARY_URL environment variable. For example, to set a temporary environment variable:
- On Mac or Linux:
- On Windows:
You may prefer to set up a persistent environment variable so that you don't have to add it every time you open a new terminal, but be aware that you could put your API secret at risk if you're storing it in your shell's startup script.
Check your configuration by entering the following CLI command:
Here's the type of response to expect:
cloud_name: <CLOUD_NAME> api_key: <API_KEY> api_secret: ***************<LAST_4_DIGITS> private_cdn: <True|False>
Before we jump into the fun stuff, take a look at this video to see how easy it is to get the CLI up and running, plus a few basic commands in action:
Now you know the basics, keep reading for some examples of what you can do with the CLI.
Uploading Assets
Let's start with an upload example. When uploading assets to Cloudinary there are many options that you can specify. To make uploading easier you can save a set of options in an upload preset. Want to know what upload presets you have configured in your account? No need to log in to your console, just enter:
You'll get back a listing of all the account upload presets including the upload options defined for each one.
Can’t find one that meets your needs? No worries - just create a new one with cld admin create_upload_preset together with any of the upload parameters documented in the API reference:
cld admin create_upload_preset name=new_preset use_filename=true unique_filename=false
Next, use the upload command to upload a single file using the upload preset (this example assumes you're running the command from the same folder as video.mp4, otherwise you'd need to specify the file path):
Or, if you have a whole directory (folder) to upload, you can use the upload_dir command. This command is unique to the CLI - it's not part of the upload API - so has different syntax. Notice that the upload preset is specified with the -p option this time, and the Cloudinary folder with -f:
The following video shows some of these commands in action. A folder of images is uploaded to Cloudinary using an upload preset that removes the backgrounds of the images by activating the Cloudinary AI Background Removal add-on:
-
Here's the
create_upload_presetcommand from the video: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
The optional parameter,
background_removal=cloudinary_ai, tells it to use the Cloudinary AI Background Removal add-on. - The details of the ‘remove_background’ upload preset are shown using the command:
-
The
upload_dircommand is used to upload the ‘soft_toys’ folder together with its contents and sub-folder to the ‘new_toys’ folder in the Cloudinary account. Because the 'remove_background' upload preset is specified, the image backgrounds are removed on upload. Here's the command:
migrate command. If this is something you're interested in, be sure to check out the migrate example in the docs. Prompt Me!
The make command is very nifty if you want to embed one of Cloudinary’s front-end tools into your app. It returns template code for implementing one of Cloudinary's widgets or players. For example, you can get the HTML you need to embed the upload widget into your web page by entering:
Here’s the 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>In Search of Answers
The search command can be incredibly useful for running queries on your assets. Want to know which assets have been rejected by one of our moderation services? Just enter:
Or, perhaps you want to know which files are eating up your storage space…
The double quotes prevent the > character redirecting to a file called 10m!
Anything you can do with the Search API, you can do with the search command, so be sure to take a look at the expressions and fields that we support, if you're not already familiar with them.
Trying Out Transformations
Had your eye on a particular transformation but not set up a coding environment yet? If all you want to do is try out some transformation parameters, then you can of course enter a URL into a browser. But that means remembering the structure of the URL. If you know the public ID of your asset and which transformations you want to try, then the url command can be very handy. For example, say you have a picture of a bear (bear.jpg) in the top level of your Cloudinary account, and you want to try the cartoonify effect on it, enter the following command:
The URL is returned, and also opened in a browser because the -o option was given:
Sign Here
Even if you have a great memory, and could rattle off a URL in a browser in no time, when it comes to signed URLs it’s not that easy. With the CLI it’s as simple as adding the -s option to the url command.
For example, you may want to try out the Cloudinary Object-Aware Cropping add-on, to crop your bear image keeping only the bear. The add-on requires the URL to be signed by default, so this command does the job:
The returned URL includes the required signature (s--dbEUpIJT--):
http://res.cloudinary.com/demo/image/upload/s--dbEUpIJT--/w_300,g_bear,c_thumb/bear.jpg
Scripted Solutions
The beauty of working with any CLI is that you can call commands from a script, making repetitive or periodic tasks a breeze.
The multi method in the upload API can be used to create an animation from images that have the same tag. The following video shows how you can use a script to upload the same image multiple times with the same tag but different public IDs, adjusting the color saturation each time. The multi method is used at the end to create the animation.
Take a look:
Here’s the script that's used in the video (note that you'd need to specify the file path to umbrellas.jpg if you didn't run the script from the same folder):
#!/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" folder="color" overwrite=true tags="umbrella" $trans
((inc++))
done
cld uploader multi umbrella delay=100The last command in the script creates the animated GIF with a delay of 100 milliseconds between frames.
If you’re a fan of scripts, I’m sure you can think of plenty more uses for the CLI, perhaps within a Jenkins or cron job. For example, you could set up a cron job to run the sync command periodically to keep a Cloudinary folder in sync with a local folder, or vice versa (see the sync documentation for details). Or, you could automatically check your credit usage each day using cld admin usage to warn you if you’re approaching your limit.
Explode and Regenerate
Here’s an example of some more creative commands in action.
Image sprites incorporate multiple images into one and therefore reduce the number of server requests required to download the images, saving bandwidth and reducing page load times. The following video shows images being extracted from a PDF, then re-combined as an image sprite, so that they can be displayed on a website:
First, the PDF is uploaded to Cloudinary, with a public ID of ‘blue_signs’:
The explode method is called 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.
The derived images are then uploaded to Cloudinary as new original images and assigned the same tag, blue_signs:
cld uploader upload http://res.cloudinary.com/carl/image/upload/pg_1/blue_signs.png tags=blue_signs cld uploader upload http://res.cloudinary.com/carl/image/upload/pg_2/blue_signs.png tags=blue_signs cld uploader upload http://res.cloudinary.com/carl/image/upload/pg_3/blue_signs.png tags=blue_signs
You’ll see in the video that each of the new images has a random public ID, as no public IDs are specified on upload. This has implications when the sprite is generated as the images are added in alphabetical order, so if you want to keep them in a specific order, be sure to upload them with appropriate public IDs.
Finally, the generate_sprite method is used to create the image sprite along with the CSS required to use each of its images on a website. Notice that a transformation is applied to each of the images added to the sprite to crop them to a square:
cld uploader generate_sprite blue_signs transformation=’{“width”: 200, “height”: 200, “crop”: “fill”, “gravity”: auto}’You’re in Command
Of course, the CLI is no substitute for real SDK or REST API code when you’re creating your app or website, but it does add another dimension to the way you can interact with Cloudinary. In addition to giving you access to Cloudinary’s APIs outside of a formal coding environment, it can ease the administrative side of managing your Cloudinary account, provide some extra functionality and give you an efficient way to try out all the great features that Cloudinary has to offer.
For more information and examples, check out the Cloudinary CLI documentation.
Go on, give it a go! That’s a command!
