Cloudinary Shell logov2.0.0

Cloudinary Shell

The lazy way to handle Cloudinary in your frontend.

Stop opening web dashboards to search folders and copy-paste public IDs. Connect cldsh to Claude Code, Claude Desktop, or Cursor, and let your AI inspect media, grab asset IDs, and write production <Image> components directly from chat. Deletes and overwrites wait for your confirmation.

npm Package
Claude Code · Cursor● MCP Active
You (in Claude Code / Cursor)

"Add hero banner from Cloudinary to landing page."

AI called cloudinary_list({ path: "portfolio" })
→ Found: portfolio/hero (1200×630)
<Image
src="https://res.cloudinary.com/.../hero"
width={1200} height={630} priority
/>
✨ Zero web console tabs. Zero copy-pasting. Done in 3 seconds.
How it works

From chat prompt to production image code

cldsh operates at the tool level—connecting your Cloudinary account directly into your AI coding tool's function calling system.

01Prompt

User prompt

Describe what you need in natural chat directly inside your editor.

Example:"Add hero banner from Cloudinary to landing page"
02Tool Call

Tool selection

Model calls the native cldsh MCP tool without manual intervention.

Autonomous Call:cloudinary_list({ path: "portfolio" })
03Discovery

Asset match

cldsh queries your account and reads live dimensions & formats.

Found Asset:portfolio/hero (1200×630, png)
04Generated

Result in code

AI writes the production-ready component code directly into your file.

Component Output:<Image src=".../hero" width={1200} ... />
Config setup

Connect in 30 seconds

Zero app code dependencies. Register cldsh in your AI editor or config file using either method below:

Example AJSON Config

Configuration file (.mcp.json)

Used by Claude Desktop, Claude Code, omp, or project-level MCP tools. Add "--read-only" to the args to expose only the read tools.

.mcp.json / claude_desktop_config.json
{
"mcpServers": {
"cloudinary": {
"command": "npx",
"args": ["-y", "cloudinary-shell", "--mcp"]
}
}
}
Example BIDE GUI

IDE settings (Cursor)

  1. Open Settings → MCP
  2. Click "Add new MCP server"
  3. Set Name: cloudinary · Type: command
Command input field
npx -y cloudinary-shell --mcp
Example COne-liner

Claude Code

Register the server in one command, then run cldsh mcp to check the handshake, list the tools and make a live call on your account.

terminal
$ claude mcp add cloudinary npx -y cloudinary-shell --mcp
$ cldsh mcp
Safety

Your agent asks before it deletes

Destructive changes take two calls. The first returns the full plan and a confirm token; nothing changes until the agent calls again with that token.

Two-Step Changes

Preview, then confirm

cloudinary_delete, cloudinary_move, folder renames and overwriting uploads return a plan first. Tokens are single-use, expire after 5 minutes and stop working if the account changes.

cloudinary_delete
→ { target: "campaigns/fall", recursive: true }
← needs_confirmation: 3 assets, 1 folder, 2.1 MB
→ { ...same args, confirm_token }
← deleted 3 · not found 0 · failed 0

Guard rails on by default

  • --read-only: exposes only list, tree, info, get_url and account tools.
  • Local sandbox: uploads and downloads stay inside the working directory, client roots and --allow-path folders; ~/.ssh and credentials are always refused.
  • Tool annotations: every tool is marked read-only, destructive or idempotent so clients know when to ask you.
  • dry_run: previews any change without touching your account.
  • Folder modes: dynamic (every account since June 2024) and fixed folders are detected automatically; moves keep delivery URLs in dynamic mode.
CLI mode

When you want to stay in your shell

Need to upload a batch of assets, check an image without opening Chrome, or wire Cloudinary into CI?

Batch Upload

Sync entire folders recursively

Mirror local project assets into Cloudinary with subfolders. Resource types come from file extensions; large files upload in chunks with retries.

terminal
$~ cldsh upload ./public/assets -r --to site/assets
Inline Graphics

Preview images inside your terminal

Renders high-res previews and test transformations directly in Warp, iTerm2, WezTerm, or VS Code terminal.

terminal
$~ cldsh view hero --t="w_400,f_auto"
Scripts & CI

JSON output and real exit codes

Results on stdout, progress and errors on stderr. Exit 0 success, 1 error, 2 usage, 3 partial failure, 4 needs --yes.

ci.sh
$ cldsh ls portfolio --json | jq -r '.files[].secure_url'
$ cldsh rm 'old-*' --dry-run
$ cldsh rm -r archive/2023 --yes

Skip the web dashboard

Config once in your AI tool. Let Claude and Cursor write the media code.

npm Package