Cloudinary Shell (cldsh)

MCP server, interactive shell and scriptable CLI for Cloudinary

cldsh lets you work with a Cloudinary account like a file system:

• AI agents (Claude Desktop, Claude Code, Cursor) get Cloudinary tools through the Model Context Protocol (MCP), with previews and confirmation before anything is deleted or replaced.

• Developers get an interactive shell with folders, tab completion, history and inline image previews.

• Scripts and CI get single commands with JSON output and meaningful exit codes.

It works with both Cloudinary folder modes: dynamic folders (every account created since June 2024) and the older fixed folders. The mode is detected automatically.

Working on a project that uses Cloudinary? Give INTEGRATION.md to your AI agent or team: integration patterns (Next.js, React, Node.js, Python), transformation recipes and cldsh workflows.

How cldsh compares

Cloudinary also publishes an official CLI (cloudinary-cli, Python) and official MCP packages (@cloudinary/*). cldsh is a separate, independent project built for a different workflow: one Node binary that is a shell, a scriptable CLI and an MCP server together, authenticated with your existing API key — no Python runtime, no OAuth browser flow, no hosted service required.

Pick cldsh for one local tool, API-key auth and a safety net on AI-driven changes. Pick the official packages for Cloudinary-maintained, domain-split MCP servers with OAuth and enterprise support.

Related MCP server: cloudflare-mcp-pro

Quick start

Requires Node.js 20 or newer and a Cloudinary account (cloud name, API key and API secret, or a CLOUDINARY_URL).

# AI agents: add the MCP server to Claude Code
claude mcp add cloudinary npx -y cloudinary-shell --mcp

# Developers: open the interactive shell
npx cloudinary-shell

# Scripts: run one command
npx cloudinary-shell ls products --json

Install globally to get the shorter cldsh command: npm install -g cloudinary-shell.

MCP server (for AI agents)

cldsh --mcp runs an MCP server over stdio (JSON-RPC 2.0). It supports protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

Client setup

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cloudinary": {
      "command": "npx",
      "args": ["-y", "cloudinary-shell", "--mcp"]
    }
  }
}

Claude Code: claude mcp add cloudinary npx -y cloudinary-shell --mcp

Cursor: Settings → MCP → Add new MCP server, type command, command npx -y cloudinary-shell --mcp.

Check the setup with cldsh mcp: it runs the handshake, lists the tools and makes a live call on your account.

Tools

Every tool carries MCP annotations (read-only, destructive, idempotent), so clients can decide when to ask you.

Safety

• Two-step changes. cloudinary_delete, cloudinary_move, cloudinary_rename_folder, and uploads that would replace existing assets first return a preview with a confirm_token. Nothing changes until the agent calls again with the same arguments and that token. Tokens are single-use, expire after 5 minutes and stop working if the account changes. dry_run: true only previews.

• Local files. Uploads and downloads can only reach the folder the server was started in, the folders your MCP client shares as roots, and folders added with --allow-path. The cldsh credentials folder, ~/.ssh and hidden files (unless named explicitly) are always refused. Downloads never overwrite a local file unless overwrite: true.

• Server options:

  • --read-only: only the read-only tools (list, tree, info, get_url, account).

  • --allow-path <dir>: allow another local folder (repeatable).

  • --no-confirm: run changes in one call, as in cldsh 1.x. Use only for trusted automation.

"args": ["-y", "cloudinary-shell", "--mcp", "--read-only"]

Command line (for scripts and CI)

Run any command directly: cldsh <command> [arguments] [options].

• Results go to stdout; progress, warnings and errors go to stderr.

• --json prints machine-readable JSON on stdout (errors are printed as JSON on stderr).

• Exit codes: 0 success, 1 error, 2 wrong usage, 3 partly failed (for example 2 of 50 uploads failed), 4 needs confirmation (add --yes) or was cancelled.

• --profile <name> uses a saved profile for one command.

# Upload a build folder with subfolders
cldsh upload ./dist/assets -r --to site/assets

# CDN URLs of every asset in a folder
cldsh ls portfolio --json | jq -r '.files[].secure_url'

# Assets larger than 100 KB
cldsh ls portfolio --json | jq -r '.files[] | select(.bytes > 100000) | .public_id'

# Preview a delete, then run it without the question
cldsh rm 'old-*' --dry-run
cldsh rm -r archive/2023 --yes

Quote wildcards. Your shell expands an unquoted cld* into local file names before cldsh sees it. Write cldsh rm 'cld*'. If every name given to rm exists in the local directory, cldsh refuses and reminds you.

Interactive shell

Run cldsh with no arguments.

Connected to Cloudinary account: my-cloud (global credentials profile (default))
[my-cloud]$~ cd products
[my-cloud]$~/products ls -l

      SIZE(KB)  DIMENSIONS(px)  NAME      FORMAT  TYPE
      ────────  ──────────────  ────────  ──────  ─────
           245  1200x630        hero      png     image
            15  512x512         logo      svg     image
          1830  1920x1080       promo     mp4     video

• The prompt shows the account (and profile) and the current folder.

• Tab completes commands, options, folder paths (cd apps/<Tab>) and asset names.

• History is kept across sessions in ~/.cldsh_history (private file; lines with credentials are never saved).

• Paths are relative to the current folder; / or ~ is the root, .. goes up, cd - goes back.

• help lists all commands; help <command> lists all options of one command.

Commands

Options shared by many commands:

Assets can be named by their name in the current folder, by path (products/hero), by public ID, or as asset_id:<id>. If a name matches several assets (for example an image and a video called intro), cldsh lists them; add --rt or use the public ID.

Uploading

[my-cloud]$~/products upload ~/Pictures/hero.png
Uploaded (created): https://res.cloudinary.com/my-cloud/image/upload/v1730000000/products/hero.png

[my-cloud]$~ upload ./media -r --to campaigns/fall
[1/3] created https://res.cloudinary.com/my-cloud/image/upload/.../campaigns/fall/banner.png
[2/3] created https://res.cloudinary.com/my-cloud/video/upload/.../campaigns/fall/teaser.mp4
[3/3] created https://res.cloudinary.com/my-cloud/raw/upload/.../campaigns/fall/notes.txt

• The resource type comes from the file extension: images (including PDF and SVG) → image, video and audio → video, everything else → raw. --rt overrides it.

• Images and videos get a public ID without extension; raw files keep it (notes.txt).

• -r includes subdirectories as subfolders. Dotfiles are skipped.

• Existing assets are overwritten and reported as overwritten; --no-overwrite keeps them (skipped).

• When two files would get the same public ID (photo.jpg, photo.png), both get their extension as suffix (photo_jpg, photo_png).

• Files over 20 MB are uploaded in chunks with progress; temporary failures are retried.

• --dry-run shows the planned public IDs and works without credentials.

Deleting

[my-cloud]$~/products rm hero
deleted  products/hero
Deleted 1 · not found 0 · failed 0

[my-cloud]$~ rm -r campaigns/fall
Delete 3 assets (1 image, 1 video, 1 raw, 2.1 MB) and 1 folder in cloud my-cloud:
  ...
Proceed? [y/N]

• rm -r deletes everything in the folder and its subfolders (all resource and delivery types), then the folder.

• Recursive deletes, wildcard deletes and deletes of more than 20 assets show the plan and ask first. Emptying the whole account asks you to type the cloud name. -y skips the question; scripts need --yes.

• Every asset is reported as deleted, not found or failed, and the exit code is 3 if anything was not found or failed.

• --skip-backup deletes folders that still hold backups of deleted assets.

Moving and renaming

[my-cloud]$~/products mv hero archive/
Moved: /products/hero -> /archive/hero (URL unchanged)

• Dynamic folder mode: moving and renaming keep the delivery URL (the folder and display name change). --public-id also renames the public ID, which changes the URL. Folders can be moved and renamed: mv products catalog/products.

• Fixed folder mode: the folder is part of the public ID, so moving or renaming changes the URL. Cloudinary can't move folders in this mode.

• An existing target stops the move; -o goes ahead. In dynamic mode, -o only replaces an asset with the same public ID; an asset that merely has the same name is kept.

• --dry-run shows whether the URL will change.

URLs, previews and downloads

url hero                          # delivery URL
url hero --t="f_auto,q_auto,w_800" # with a transformation
url 'banner-*'                    # several assets
url private-doc --signed          # signed URL for authenticated assets
view hero --t="e_grayscale"       # inline preview (iTerm2, WezTerm, Ghostty, VS Code, Warp)
download 'shots/*' ./shots/       # several files into a folder

• Unsigned URLs without --t are exactly the asset's secure_url.

• view prints the preview URL when the terminal can't show images.

• download skips local files that already exist unless -f; private and authenticated assets download through signed URLs.

Accounts and credentials

# Interactive (the secret is not shown while you type)
cldsh login

# From a script, without putting the secret in your shell history
printf %s "$CLOUDINARY_URL" | cldsh login prod --stdin

cldsh config ls          # saved profiles
cldsh config use prod    # switch (also inside the shell)
cldsh config             # active account, where it comes from, what it overrides

Profiles are stored in ~/.config/cldsh/credentials.json (%APPDATA%\cldsh on Windows) with owner-only permissions. Writes are atomic, and a damaged file is never overwritten (login --reset moves it aside).

When several sources are present, the strongest wins:

1. --profile <name>, config use / login in the current shell, or CLOUDINARY_PROFILE

2. CLOUDINARY_URL (or CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET) in the environment

3. A .env file in the current directory

4. The saved default profile

cldsh warns at startup, and config shows, when a source is overridden. CLOUDINARY_URL options such as ?upload_prefix=https://api-eu.cloudinary.com (EU/AP data centers) and private CDN settings are supported.

Folder modes and API limits

• cldsh detects the folder mode of your account. Override it with --folder-mode=fixed|dynamic or CLDSH_FOLDER_MODE.

• Listing folders and assets uses Cloudinary's Admin API, which is rate-limited per hour (500 requests on the Free plan). cldsh caches listings for a few seconds, warns when less than 10% of the hourly budget is left, and quota shows the remaining requests. Uploads and delivery URLs don't count.

• In fixed folder mode, listing a folder also pages through its subfolders' assets, so very large folders cost more requests.

Troubleshooting

License

MIT. See CHANGELOG.md for changes between versions.