Cldsh Cloudinary Shell

Cloudinary Shell (cldsh)

MCP server, interactive shell and scriptable CLI for Cloudinary

[npm version] [License: MIT] [MCP Protocol]

[cldsh demo: tab completion, a colored ls -l listing, a transformed delivery URL, and a recursive delete that previews the plan and asks before anything is removed]

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 Codeclaude mcp add cloudinary npx -y cloudinary-shell --mcp
# Developers: open the interactive shellnpx cloudinary-shell
# Scripts: run one commandnpx 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 subfolderscldsh upload ./dist/assets -r --to site/assets
# CDN URLs of every asset in a foldercldsh ls portfolio --json | jq -r '.files[].secure_url'
# Assets larger than 100 KBcldsh ls portfolio --json | jq -r '.files[] | select(.bytes > 100000) | .public_id'
# Preview a delete, then run it without the questioncldsh rm 'old-*' --dry-runcldsh 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.pngUploaded (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 herodeleted  products/heroDeleted 1 · not found 0 · failed 0
[my-cloud]$~ rm -r campaigns/fallDelete 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 URLurl hero --t="f_auto,q_auto,w_800" # with a transformationurl 'banner-*'                    # several assetsurl private-doc --signed          # signed URL for authenticated assetsview 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 historyprintf %s "$CLOUDINARY_URL" | cldsh login prod --stdin
cldsh config ls          # saved profilescldsh 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.