Cloudinary CLI for coding agents

When you give a coding agent access to a project's shell, it can use the Cloudinary CLI to call Cloudinary’s media APIs from terminal commands. The CLI runs as cld and can generate delivery URLs or manage assets. A delivery URL is the address your code or browser uses to retrieve an asset from Cloudinary.

The CLI uses Cloudinary’s Python SDK, a library that lets Python programs work with Cloudinary, and its commands can change your account. For an agent task, start with a read-only step: check the CLI’s help output for the available syntax before asking the agent to inspect or change assets. Cloudinary’s command overview describes the command groups and common uses.

Install and authenticate

The installation instructions require Python 3.8 or later and recommend pipx, a tool that installs a Python command-line app in its own environment. The page also lists other methods, like pip and a Docker image. Install the CLI in the environment where the agent will run shell commands, then check the version:

pipx install cloudinary-cli
cld --version

On your own machine, the docs recommend cld login. It opens a browser so you can sign in with OAuth, a standard way to grant access without copying the API key and secret, and saves the session as a named configuration. For CI or shared scripts, set the CLOUDINARY_URL environment variable instead. The variable combines an API key, an API secret, and a cloud name in this form:

cloudinary://<API_KEY>:<API_SECRET>@<CLOUD_NAME>

The angle-bracket values are placeholders. Use a local secret manager, or another method that keeps the value out of the agent prompt and committed files, to set it. The API secret grants access to account operations. Do not paste it into a chat or put it in public client-side code. Cloudinary’s Upload API documentation warns against exposing the secret in client-side code, and the CLI page says to run CLI scripts only locally or in server applications.

The CLI also documents cld config --from_url for saving credentials as a configuration that is named after the cloud. Use -C <cloud_name> to choose that configuration when you run a command. The documented command shape is cld -C <cloud_name> <command>. The placeholder <cloud_name> stands for the configuration name, which here is the cloud name of your account. Configuration commands set up the CLI on your computer. Upload, deletion, and other API commands contact Cloudinary and can change account data.

Inspect a command before using it

For a first task, ask the agent to prepare a delivery URL for an existing asset. Have it check the CLI’s available commands and the URL command’s usage:

cld --help
cld url --help

The first command shows the CLI’s available commands. The second shows the URL command’s syntax and options. These help commands read information stored with the CLI. They do not search Cloudinary or change assets. Follow the syntax shown by the installed CLI instead of guessing option names or assuming what its output looks like.

Cloudinary documents cld url as a helper for generating delivery URLs. An agent can use it to get a URL for an existing media asset referenced in project code. The documented syntax is cld url [command options] public_id [transformation], and the command returns a URL to use in the project. With the -o option, the CLI generates the derived asset and opens it in a browser. The docs note that the derived asset isn't generated until the URL is opened. The command reference also documents API command groups such as cld uploader and cld admin. These groups handle other account tasks. Check their command help before running a command that uploads or manages remote assets.

The example above only reads local CLI help. It does not produce a URL or return asset details. It shows the agent the actual syntax before it runs a URL-generation command with a real public ID. A public ID is Cloudinary’s identifier for an asset, such as the name your code uses to refer to an uploaded image.

Keep URL generation separate from uploads

Generating a delivery URL and uploading an asset do different things. URL generation prepares an address for an existing asset. An upload sends a local file or remote source to Cloudinary and creates or updates an asset in your account. The CLI documentation shows an upload of a local file with its own public ID and folder. The Upload API reference also accepts the remote HTTP or HTTPS address of an existing file as the source.

Handle uploads as a separate step that changes your account. Before running an upload command, confirm the local file and intended public ID, then check the CLI’s help for the exact arguments. The cited documentation does not establish a universal preview or dry-run flag. Do not assume a flag such as --dry-run prevents an upload.

A realistic prompt for the read-only example is:

Use the installed Cloudinary CLI to prepare a delivery URL for the existing asset with public ID <PUBLIC_ID>. First inspect cld url --help, then use the documented syntax. Do not upload, delete, or modify assets. Report the resulting URL and the command you used, without printing credentials.

This prompt gives the agent a specific task and limits it to generating a URL. Keep credentials in the environment, not the prompt.