cldsh-Cloudinary-Shell

Cloudinary Shell (cldsh)

Cloudinary 用の MCP サーバー、対話型シェル、スクリプト対応 CLI

cldsh を使うと、Cloudinary アカウントをファイルシステムのように操作できます。

• AI エージェント（Claude Desktop、Claude Code、Cursor）は、Model Context Protocol（MCP）経由で Cloudinary ツールを利用できます。削除や置換の前には、プレビューと確認が行われます。
• 開発者は、フォルダー、タブ補完、履歴、画像のインラインプレビューに対応した対話型シェルを利用できます。
• スクリプトや CIでは、JSON 出力と意味のある終了コードを返す単一のコマンドを利用できます。

Cloudinary の両方のフォルダーモードに対応しています。動的フォルダー（2024 年 6 月以降に作成されたすべてのアカウント）と、従来の固定フォルダーです。モードは自動的に検出されます。

Cloudinary を使うプロジェクトに取り組んでいますか？INTEGRATION.md を AI エージェントまたはチームに共有してください。統合パターン（Next.js、React、Node.js、Python）、変換レシピ、cldsh のワークフローが記載されています。

---

cldsh の比較

Cloudinary は公式 CLI（cloudinary-cli、Python）と公式 MCP パッケージ（@cloudinary/*）も公開しています。cldsh は、異なるワークフロー向けに構築された独立プロジェクトです。シェル、スクリプト対応 CLI、MCP サーバーを兼ねる 1 つの Node バイナリで、既存の API キーを使って認証できます。Python ランタイムも OAuth のブラウザーフローも、ホスト型サービスも必要ありません。

	cldsh	cloudinary-cli（公式）	@cloudinary/* MCP（公式）	コミュニティ製 MCP サーバー
ランタイム	Node、npx	Python、pipx／Docker	パッケージごとに Node、npx	Node、npx
認証	API キー／.env	OAuth ログイン	OAuth（ホスト型）または API キー	API キー
対話型シェル（cd、ls、タブ補完）	✅	❌ 単発のフラグ	❌ CLI ではありません	❌ CLI ではありません
MCP サーバー	✅ 同じバイナリ	❌	✅（個別の 5 パッケージ）	✅
削除／移動／上書き前の確認	✅ 2 段階トークン、--dry-run	❌	—	❌
固定／動的フォルダーモード	✅ 自動検出	記載なし	記載なし	記載なし

ローカルで使える単一のツール、API キー認証、AI による変更のセーフティネットを求めるなら cldsh を選んでください。Cloudinary が保守する、ドメイン別に分かれた MCP サーバー、OAuth、エンタープライズサポートを求めるなら公式パッケージを選んでください。

---

クイックスタート

Node.js 20 以降と、Cloudinary アカウント（cloud name、API キーと API シークレット、または 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 エージェント向け）

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	1つのアセットのすべてのメタデータを表示します	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 アノテーション（読み取り専用、破壊的、べき等）が付与されているため、クライアントは確認を求めるタイミングを判断できます。

安全性

• 2段階で変更します。 cloudinary_delete、cloudinary_move、cloudinary_rename_folder、および既存のアセットを置き換えるアップロードでは、最初に confirm_token を含むプレビューが返されます。エージェントが同じ引数とそのトークンを指定して再度呼び出すまで、変更は行われません。トークンは1回のみ使用でき、有効期限は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 と同様に、変更を1回の呼び出しで実行します。信頼できる自動化でのみ使用してください。

"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> を指定すると、保存済みのプロファイルを1つのコマンドで使用します。

# 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

ワイルドカードは引用符で囲んでください。 引用符で囲まれていない cld* は、cldsh が受け取る前にシェルによってローカルのファイル名に展開されます。cldsh rm 'cld*' のように記述してください。rm に指定した名前がすべてローカルディレクトリに存在する場合、cldsh は処理を拒否して、その旨を通知します。

---

対話型シェル

引数を指定せずに 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 フォルダーを変更、表示します（シェルのみ）
lcd、lpwd	ローカルディレクトリを変更、表示します
mkdir <folder>...	フォルダーを作成します（親フォルダーも含む）
upload <path> [name] [--to folder] [-r]	ファイルまたはディレクトリをアップロードします
download <name|pattern>... [destination] [-f]	アセットをダウンロードします
mv <source> <target> [-o] [--public-id]	アセットまたはフォルダーを移動または名前変更します
info <name>	アセットのメタデータを表示します（完全な API 応答は -v）
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）、パブリック ID、または asset_id:<id> で指定できます。名前が複数のアセットに一致する場合（たとえば、intro という名前の画像と動画がある場合）、cldsh はそれらを一覧表示します。--rt を追加するか、パブリック 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 で上書きできます。
• 画像と動画のパブリック ID には拡張子が付きません。raw ファイルには拡張子が付きます（notes.txt）。
• -r を指定すると、サブディレクトリをサブフォルダーとして含めます。ドットファイルはスキップされます。
• 既存のアセットは上書きされ、overwritten として報告されます。--no-overwrite を指定すると保持され、skipped として報告されます。
• 2 つのファイルが同じパブリック ID になる場合（photo.jpg、photo.png）、どちらも拡張子が接尾辞として付加されます（photo_jpg、photo_png）。
• 20 MB を超えるファイルは進行状況を表示しながら分割アップロードされます。一時的な失敗は再試行されます。
• --dry-run は予定されているパブリック 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 個を超えるアセットの削除では、実行内容を表示して確認を求めます。アカウント全体を空にする場合は、クラウド名の入力が必要です。-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 を指定するとパブリック ID も変更され、URL が変わります。フォルダーの移動と名前変更ができます：mv products catalog/products。
• 固定フォルダーモード： フォルダーはパブリック ID の一部であるため、移動や名前変更をすると URL が変わります。Cloudinary ではこのモードでフォルダーを移動できません。
• 移動先がすでに存在する場合、移動は中止されます。-o を指定すると続行します。ダイナミックモードでは、-o は同じパブリック 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 を出力します。
• download は、-f を指定しない限り、すでに存在するローカルファイルをスキップします。プライベートアセットと認証が必要なアセットは、署名付き 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>、現在のシェルでの config use／login、または CLOUDINARY_PROFILE
2. 環境内の CLOUDINARY_URL（または CLOUDINARY_CLOUD_NAME、CLOUDINARY_API_KEY、CLOUDINARY_API_SECRET）
3. 現在のディレクトリにある .env ファイル
4. 保存されたデフォルトプロファイル

設定元が上書きされると、cldsh は起動時に警告し、config はその内容を表示します。?upload_prefix=https://api-eu.cloudinary.com（EU／AP データセンター）などの CLOUDINARY_URL オプションや、プライベート CDN の設定にも対応しています。

---

フォルダモードと API の制限

• cldsh はアカウントのフォルダモードを検出します。--folder-mode=fixed|dynamic または CLDSH_FOLDER_MODE で上書きできます。
• フォルダとアセットの一覧取得には Cloudinary の Admin API を使用し、1 時間あたりのリクエスト数に制限があります（Free プランでは 500 リクエスト）。cldsh は一覧を数秒間キャッシュし、1 時間あたりの上限の残りが 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	シェルによってワイルドカードが展開されています。引用符で囲んでください：cldsh rm 'cld*'。
needs an interactive terminal／終了コード 4	コマンドで確認が求められています。スクリプトでは --yes を追加してください。
matches 2 assets	--rt=image（または video／raw）を追加するか、パブリック ID を使用してください。
レート制限に達した	cldsh quota で、1 時間あたりの上限がリセットされる時刻を確認できます。

---

ライセンス

MIT。バージョン間の変更については、CHANGELOG.md をご覧ください。