Cldsh Cloudinary Shell

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.

---

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 : 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 [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 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/ ) 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 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: . 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,