cldsh-Cloudinary-Shell

Cloudinary Shell（cldsh）

用于 Cloudinary 的 MCP 服务、交互式 Shell 和可编写脚本的 CLI

cldsh 让你像操作文件系统一样使用 Cloudinary 账户：

• AI Agent（Claude Desktop、Claude Code、Cursor）通过 Model Context Protocol（MCP）使用 Cloudinary 工具，删除或替换任何内容前都会先预览并征求确认。
• 开发者可使用带文件夹、Tab 补全、历史记录和内嵌图片预览的交互式 Shell。
• 脚本和 CI可使用输出 JSON 且返回有意义退出码的单条命令。

它支持 Cloudinary 的两种文件夹模式：动态文件夹（自 2024 年 6 月起创建的所有账户）和较早的固定文件夹。系统会自动检测模式。

正在开发使用 Cloudinary 的项目？将 INTEGRATION.md 提供给你的 AI Agent 或团队：其中包含集成模式（Next.js、React、Node.js、Python）、转换方案和 cldsh 工作流。

---

cldsh 对比

Cloudinary 也发布了官方 CLI（cloudinary-cli，Python）和官方 MCP 软件包（@cloudinary/*）。cldsh 是一个独立项目，面向不同的工作流：一个 Node 二进制程序，同时提供 Shell、可编写脚本的 CLI 和 MCP 服务，并使用你现有的 API 密钥进行身份验证——无需 Python 运行时、OAuth 浏览器流程或托管服务。

	cldsh	cloudinary-cli（官方）	@cloudinary/* MCP（官方）	社区 MCP 服务
运行时	Node，npx	Python，pipx/Docker	Node，每个软件包使用 npx	Node，npx
身份验证	API 密钥 / .env	OAuth 登录	OAuth（托管）或 API 密钥	API 密钥
交互式 Shell（cd、ls、Tab 补全）	✅	❌ 一次性标志	❌ 不是 CLI	❌ 不是 CLI
MCP 服务	✅ 同一二进制程序	❌	✅（5 个独立软件包）	✅
删除/移动/覆盖前确认	✅ 两步令牌，--dry-run	❌	—	❌
固定/动态文件夹模式	✅ 自动检测	未注明	未注明	未注明

如需使用一个本地工具、API 密钥身份验证，并为 AI 驱动的更改提供安全保障，请选择 cldsh。如需使用由 Cloudinary 维护、按领域拆分且支持 OAuth 和企业功能的 MCP 服务，请选择官方软件包。

---

快速开始

需要 Node.js 20 或更高版本以及 Cloudinary 账户（cloud name、API key 和 API secret，或 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

全局安装即可使用更短的 cldsh 命令：npm install -g cloudinary-shell。

---

MCP 服务（适用于 AI Agent）

cldsh --mcp 会通过 stdio 运行 MCP 服务（JSON-RPC 2.0）。它支持协议版本 2025-06-18、2025-03-26 和 2024-11-05。

客户端设置

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，类型选 command，命令为 npx -y cloudinary-shell --mcp。

使用 cldsh mcp 检查设置：该命令会执行握手、列出工具，并在你的账户上进行实时调用。

工具

工具	功能	主要参数
cloudinary_list	列出文件夹和资源（允许使用通配符）	path、resource_type、delivery_type、max
cloudinary_tree	文件夹树	folder、depth、resource_type、max_files
cloudinary_info	单个资源的完整元数据	public_id、resource_type、delivery_type
cloudinary_get_url	获取投递 URL，可选择进行转换或签名	public_id、transformation、signed、resource_type
cloudinary_upload	上传本地文件或目录	local_path、name、folder、recursive、overwrite、resource_type、dry_run
cloudinary_download	将资源下载到本地磁盘	public_id、destination、overwrite、dry_run
cloudinary_move	移动或重命名资源或文件夹	source、target、overwrite、change_public_id、dry_run
cloudinary_delete	删除资源，或使用 recursive 删除文件夹	target、recursive、resource_type、dry_run
cloudinary_mkdir	创建文件夹	folder
cloudinary_rename_folder	重命名或移动文件夹（动态文件夹模式）	from、to
cloudinary_account	云名称、文件夹模式、凭据来源、剩余 API 额度	—

每个工具都带有 MCP 注释（只读、破坏性、幂等），客户端可据此决定何时向你询问。

安全

• 两步更改。 cloudinary_delete、cloudinary_move、cloudinary_rename_folder，以及会替换现有资源的上传操作，会先返回包含 confirm_token 的预览。只有 Agent 使用相同参数和该令牌再次调用后，才会进行更改。令牌只能使用一次，有效期为 5 分钟，且账户发生变化后便会失效。dry_run: true 仅用于预览。
• 本地文件。 上传和下载只能访问服务器启动时所在的文件夹、MCP 客户端作为根目录共享的文件夹，以及通过 --allow-path 添加的文件夹。始终拒绝访问 cldsh 凭据文件夹、~/.ssh 和隐藏文件（除非明确指定）。除非设置 overwrite: true，否则下载不会覆盖本地文件。
• 服务器选项：
  • --read-only：仅启用只读工具（list、tree、info、get_url、account）。
  • --allow-path <dir>：允许访问其他本地文件夹（可重复指定）。
  • --no-confirm：像 cldsh 1.x 一样，在一次调用中执行更改。仅用于可信自动化。

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

---

命令行（用于脚本和 CI）

直接运行任意命令：cldsh <command> [arguments] [options]。

• 结果输出到 stdout；进度、警告和错误输出到 stderr。
• --json 会将机器可读的 JSON 输出到 stdout（错误会以 JSON 格式输出到 stderr）。
• 退出代码：0 表示成功，1 表示错误，2 表示用法错误，3 表示部分失败（例如 50 次上传中有 2 次失败），4 表示需要确认（添加 --yes）或操作已取消。
• --profile <name> 使用已保存的配置文件执行单条命令。

# 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

引用通配符。 如果不加引号，Shell 会在 cldsh 看到 cld* 之前将其展开为本地文件名。请写成 cldsh rm 'cld*'。如果 rm 收到的所有名称都存在于本地目录中，cldsh 会拒绝执行并提醒你。

---

交互式 Shell

不带参数运行 cldsh。

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

• 提示符会显示账户（和配置文件）以及当前文件夹。
• 按 Tab 可补全命令、选项、文件夹路径（cd apps/<Tab>）和资源名称。
• 历史记录会保存在会话之间，存放于 ~/.cldsh_history（私密文件；包含凭据的行绝不会保存）。
• 路径相对于当前文件夹；/ 或 ~ 表示根目录，.. 表示上一级，cd - 返回之前所在的位置。
• help 会列出所有命令；help <command> 会列出某条命令的所有选项。

---

命令

命令	功能
login [profile] [URL] [--stdin]	连接账户并将其保存为配置文件（首先通过 Cloudinary 验证）
config [ls | use <profile> | rm <profile>]	显示当前账户及其覆盖的来源；列出、切换或删除配置文件
ls [path|pattern] [-l]	列出文件夹和资源
cd、pwd	更改并显示当前 Cloudinary 文件夹（仅限 shell）
lcd、lpwd	更改并显示本地目录
mkdir <folder>...	创建文件夹（包括父文件夹）
upload <path> [name] [--to folder] [-r]	上传文件或目录
download <name|pattern>... [destination] [-f]	下载资源
mv <source> <target> [-o] [--public-id]	移动或重命名资源或文件夹
info <name>	资源元数据（使用 -v 查看完整 API 响应）
url <name|pattern>... [--t=...] [--signed]	交付 URL
view <name>（别名 preview）	在终端中显示图像或视频缩略图
open <name>	在浏览器中打开资源
rm [-r] <name|folder|pattern>... [-y]	删除资源，或使用 -r 删除文件夹
tree [folder] [-d N]	文件夹树
quota	查看本小时剩余的 Admin API 请求数和文件夹模式
mcp	检查 MCP 服务

许多命令通用的选项：

选项	含义
--rt=image|video|raw|all	资源类型。默认情况下，列表会显示所有类型。
--type=upload|private|authenticated	交付类型
--dry-run	显示将执行的操作，但不做任何更改
-y、--yes	不询问确认
--json	JSON 输出

资源可以通过其在当前文件夹中的名称、路径（products/hero）、public ID 或 asset_id:<id> 指定。如果某个名称匹配多个资源（例如，一张图像和一个视频都叫 intro），cldsh 会列出它们；请添加 --rt 或使用 public ID。

上传

[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

• 资源类型由文件扩展名决定：图像（包括 PDF 和 SVG）→ image，视频和音频 → video，其他所有文件 → raw。--rt 可覆盖此设置。
• 图像和视频的 public ID 不包含扩展名；raw 文件则保留扩展名（notes.txt）。
• -r 会将子目录作为子文件夹一并包含。隐藏文件会跳过。
• 已存在的资源会被覆盖，并标记为 overwritten；使用 --no-overwrite 可保留它们（标记为 skipped）。
• 如果两个文件会得到相同的 public ID（photo.jpg、photo.png），两者都会在 ID 后缀中包含扩展名（photo_jpg、photo_png）。
• 大于 20 MB 的文件会分块上传并显示进度；临时故障会触发重试。
• --dry-run 会显示计划使用的 public ID，且无需凭据即可运行。

删除

[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 会删除文件夹及其子文件夹中的所有内容（所有资源和交付类型），然后删除文件夹。
• 递归删除、通配符删除以及删除超过 20 个资源时，会显示计划并先询问确认。清空整个账户时，系统会要求你输入 cloud name。-y 可跳过确认；脚本需要使用 --yes。
• 每个资源都会标记为 deleted、not found 或 failed；如果有任何资源未找到或删除失败，退出代码为 3。
• --skip-backup 会删除仍存有已删除资源备份的文件夹。

移动和重命名

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

• 动态文件夹模式： 移动和重命名不会改变交付 URL（文件夹和显示名称会改变）。--public-id 也会重命名 public ID，从而改变 URL。可以移动和重命名文件夹：mv products catalog/products。
• 固定文件夹模式： 文件夹属于 public ID 的一部分，因此移动或重命名会改变 URL。Cloudinary 在此模式下无法移动文件夹。
• 如果目标已存在，移动操作会停止；-o 会继续执行。在动态模式下，-o 只会替换 public ID 相同的资源；仅名称相同的资源会被保留。
• --dry-run 会显示 URL 是否会改变。

URL、预览和下载

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

• 不带 --t 的未签名 URL 与资源的 secure_url 完全相同。
• 当终端无法显示图片时，view 会打印预览 URL。
• 除非使用 -f，否则 download 会跳过已存在的本地文件；私有和经过身份验证的资源会通过签名 URL 下载。

---

账户和凭据

# 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

配置文件存储在 ~/.config/cldsh/credentials.json（Windows 上为 %APPDATA%\cldsh），且仅所有者可访问。写入操作是原子性的，损坏的文件绝不会被覆盖（login --reset 会将其移至一旁）。

存在多个来源时，优先级最高的来源生效：

1. --profile <name>、当前 shell 中的 config use / login，或 CLOUDINARY_PROFILE
2. 环境中的 CLOUDINARY_URL（或 CLOUDINARY_CLOUD_NAME、CLOUDINARY_API_KEY、CLOUDINARY_API_SECRET）
3. 当前目录中的 .env 文件
4. 已保存的默认配置文件

当某个来源被覆盖时，cldsh 会在启动时发出警告，config 也会显示相关信息。支持 CLOUDINARY_URL 选项，例如 ?upload_prefix=https://api-eu.cloudinary.com（EU/AP 数据中心）以及私有 CDN 设置。

---

文件夹模式和 API 限制

• cldsh 会检测账户的文件夹模式。可使用 --folder-mode=fixed|dynamic 或 CLDSH_FOLDER_MODE 覆盖。
• 列出文件夹和资源会使用 Cloudinary 的 Admin API，该 API 有每小时调用次数限制（Free 方案为 500 次请求）。cldsh 会缓存列表几秒；当每小时额度剩余不足 10% 时会发出警告，quota 会显示剩余请求次数。上传和传送 URL 不计入额度。
• 在固定文件夹模式下，列出文件夹时也会分页遍历其子文件夹中的资源，因此非常大的文件夹会消耗更多请求。

---

故障排除

问题	处理方法
Not connected to a Cloudinary account	运行 cldsh login，或设置 CLOUDINARY_URL。cldsh config 会显示当前生效的配置。
使用了错误的账户	cldsh config 会列出正在使用的来源及其覆盖的来源。
Refusing to run "rm" on ... names that all exist in the local directory	shell 展开了通配符；请将其加上引号：cldsh rm 'cld*'。
needs an interactive terminal / exit code 4	该命令需要确认；在脚本中添加 --yes。
matches 2 assets	添加 --rt=image（或 video/raw），或使用公开 ID。
达到速率限制	cldsh quota 会显示每小时额度的重置时间。

---

许可证

MIT。版本间的变更请参阅 CHANGELOG.md。