> ## Documentation Index
> This page is part of the Image and Video APIs product. Fetch the complete documentation index for Image and Video APIs at: https://cloudinary.com/documentation/llms-image-and-video-apis.txt?referrer=docpage and then use it to discover all relevant pages before exploring further.
> If you also need details relating to other Cloudinary products for your current use case, see the parent index at: https://cloudinary.com/documentation/llms.txt?referrer=docpage

# Cloudinary VS Code Extension


The [Cloudinary VS Code Extension](https://marketplace.visualstudio.com/items?itemName=cloudinary.cloudinary) brings essential media asset management capabilities directly into your development environment. Browse, search, upload, and copy optimized asset URLs, ask the Cloudinary documentation assistant questions, and set up Cloudinary's AI tools without switching between your IDE and the Cloudinary Console.

## Overview

The Cloudinary VS Code Extension eliminates the need to switch between your IDE and browser when working with media assets, and adds AI-powered help directly in your editor.

Key features include:

* **Home dashboard**: A central panel with quick actions, library search, the Docs AI assistant, and AI tool configuration
* **Asset Explorer**: Browse your complete Media Library in a tree view that mirrors your Console folder structure
* **Search and view options**: Find assets by public ID, filter by asset type (images, videos, raw files), and sort by upload date
* **Quick copy actions**: Copy public IDs and secure or optimized URLs with a right-click
* **Direct upload**: Upload files with drag-and-drop, a file browser, or a remote URL, with folder targeting, tags, custom public IDs, and progress tracking
* **Asset preview**: View images, videos, and raw files directly in VS Code, including metadata and a full-size lightbox
* **Docs AI assistant**: Chat with the Cloudinary documentation assistant from inside your editor, with source citations and conversation history
* **Configure AI Tools**: Install Cloudinary agent skills and MCP server configuration for your AI coding assistant in one step
* **Environment management**: Switch between multiple Cloudinary product environments

Use these features to reference existing assets while coding, verify asset availability, upload test files during development, get answers from the docs without leaving your editor, and seamlessly switch between multiple Cloudinary environments.

### Integration with other tools

The VS Code Extension complements other Cloudinary developer tools:

* **MCP servers**: Use the extension for visual asset browsing, while [MCP servers](cloudinary_llm_mcp) handle programmatic operations and AI-assisted development. The extension can also install and configure these MCP servers for you (see [Configuring AI tools](#configuring_ai_tools)).
* **SDKs**: The extension helps you discover and reference assets that your [SDK](cloudinary_sdks) code can build out to Cloudinary URLs.

## Installation

You can install the Cloudinary extension from the Visual Studio Marketplace or the Open VSX Registry, depending on your IDE.

### VS Code

1. Open VS Code.
2. Navigate to the Extensions view (Ctrl/Cmd+Shift+X).
3. Search for "Cloudinary".
4. Click **Install** on the Cloudinary extension.

Alternatively, install directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=cloudinary.cloudinary).

### IDEs based on VS Code (e.g., Cursor)

If you use a VSCode-forked IDE, such as Cursor, Windsurf, VSCodium, etc, you can install the extension via the [Open VSX Registry](https://open-vsx.org/extension/cloudinary/cloudinary).

* If your IDE uses Open VSX by default (like Cursor), search for "Cloudinary" and install it directly.
* Otherwise, download the `.vsix` file from the [Open VSX Registry](https://open-vsx.org/extension/cloudinary/cloudinary) or the [GitHub releases page](https://github.com/cloudinary-devs/cloudinary-vscode/releases). Then, in your IDE's **Extensions** pane, select **Install from VSIX** from the menu.

## Configuration

The extension reads credentials from a JSON configuration file that supports both global and workspace-specific settings.

### Configuration file location

Create a configuration file at one of these locations:

* **Global configuration**: `~/.cloudinary/environments.json` (applies to all projects). On Windows, this is `%USERPROFILE%\.cloudinary\environments.json`.
* **Workspace configuration**: `.cloudinary/environments.json` at your project root (applies only to that project)

If both files exist, workspace-specific configurations take precedence over global configurations. On first use, the extension creates a global configuration file with placeholder content for you to fill in.

### Configuration format

```json
{
  "your-cloud-name": {
    "apiKey": "your-api-key",
    "apiSecret": "your-api-secret",
    "uploadPreset": "your-upload-preset"
  },
  "another-cloud-name": {
    "apiKey": "another-api-key",
    "apiSecret": "another-api-secret",
    "uploadPreset": "another-upload-preset"
  }
}
```

Each entry represents a separate Cloudinary environment that you can switch between using the home dashboard or the VS Code status bar. The cloud name is the key (the property name in the JSON object).

### Finding your credentials

You can find your credentials in the [Console Settings > API Keys](https://console.cloudinary.com/app/settings/api-keys) page:

* **Cloud name**: Your Cloudinary account identifier
* **API key**: Your public API key
* **API secret**: Your private API secret
* **Upload preset** (optional): A pre-configured upload preset name. If you omit it, uploads are signed using your API key and secret. To use a preset, create or manage upload presets in the [Upload Presets](https://console.cloudinary.com/app/settings/upload/presets) page of the Console.

> **TIP**: For security, avoid committing workspace configuration files containing API secrets to version control. Add `.cloudinary/environments.json` to your `.gitignore` file.

## Using the extension

### Home dashboard

When you open the Cloudinary panel from the Activity Bar, you land on the home dashboard. From here you can:

* **Browse Library**: Open the Media Library to explore your assets
* **Upload**: Open the upload panel to add files to your library
* **Switch Environment**: Change the active Cloudinary product environment
* **Configure AI Tools**: Install Cloudinary skills and MCP servers for your AI coding assistant
* **Search**: Search your Media Library by public ID directly from the home view
* **Ask Cloudinary AI**: Send a question to the Docs AI assistant, choose from suggested questions, and reopen recent conversations

If your credentials aren't configured yet, the dashboard shows a banner prompting you to add them.

### Browsing assets

The Library provides a tree view of your entire Media Library organized by folders, mirroring the structure you see in your Cloudinary Console.

Assets load progressively, showing a loading indicator while more are fetched. This keeps the interface responsive even with large libraries containing thousands of assets.

![Asset Explorer](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1749821507/docs/vscode_extension_tree.png "thumb: w_300,dpr_2, width:300, with_code:false, with_url:false, popup:true")

> **TIP**: If your assets use [dynamic folders](folder_modes), the folder hierarchy reflects your asset organization. For fixed folder mode, you'll see the folder structure as it was created in your Console.

### Searching assets

The search functionality helps you quickly locate specific assets without manually browsing through folders. You can search from the library's search field or from the home dashboard.

1. Click in the search box.
2. Type part of an asset's public ID.
3. Press **Enter** to search.

The search is case-insensitive and matches across the public ID, including folder names. For example, searching for "logo" matches assets like `products/logo.png`, `brand/company-logo.jpg`, and `logos/mobile/header-logo.svg`.

To clear your search and return to the folder view, click the **Clear search** entry at the top of the results.

### Filtering and sorting

Use **View Options** to control which assets are displayed and in what order.

1. Click the **View Options** (filter) button in the Library toolbar.
2. Choose a filter and sort option:
   * **Filter by type**: **All Types**, **Images Only**, **Videos Only**, or **Raw Files Only**
   * **Sort order**: **Newest First** or **Oldest First** (by upload date)

The tree view updates to reflect your selection.

### Copying asset information

The most common operation is copying asset identifiers for use in your code. The extension provides quick access to the information you need most.

Right-click (or control-click on Mac) any asset to open the context menu with these options:

* **Copy Public ID**: Copies the asset's public ID to your clipboard. This is typically what you'll pass to Cloudinary SDKs or use in transformation URLs. The public ID includes the folder path (if any) but excludes the file extension.
  * Example: `products/summer-collection/hero-image`
* **Copy URL**: Copies the asset's full HTTPS (secure) delivery URL to your clipboard.
* **Copy Optimized URL**: Copies the asset's full HTTPS optimized delivery URL to your clipboard. This is an optimized URL you can use in HTML or as an image source. The URL includes your cloud name with automatic format and quality optimization.

### Uploading assets

Upload new assets directly to your Cloudinary account without leaving your IDE.

1. Click the **Upload** button on the home dashboard or in the Library toolbar, or choose **Upload here** on a folder to pre-select that folder. You can also run **Cloudinary: Upload** from the command palette.
2. In the upload panel, add files in any of these ways:
   * **Drag and drop** files onto the drop zone
   * Click **Browse Files** to select files from your system
   * Paste a **remote URL** to upload from another source
3. Optionally set upload details:
   * **Destination Folder**: Select the target folder from the drop-down
   * **Upload preset**: Select a configured preset. This is optional; without a preset, uploads are signed using your credentials.
   * **Custom public ID**: Specify a public ID for a single file upload
   * **Tags**: Add comma-separated tags
4. Start the upload and watch real-time progress for each file.
5. Once uploaded, assets appear in the panel's gallery, where you can click to preview or copy the URL or public ID. They also appear in the Library tree view.

![Upload assets](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1749821507/docs/vscode_extension_upload.png "thumb: w_600,dpr_2, width:600, with_code:false, with_url:false, popup:true")

### Previewing assets

Preview images, videos, and raw files directly within VS Code to verify they're the assets you need before referencing them in code.

1. Click on any asset in the tree view or search results to open the preview panel.
2. For images and videos, the panel shows a compact preview with an enlarge button that opens a full-size lightbox. Videos include playback controls.
3. Raw files show file details and a download link rather than a visual preview.

The panel's **Info**, **Metadata**, and **URLs** tabs show:

* **Info**: Public ID, original filename, dimensions, file size, type, and delivery type
* **Metadata**: Tags, context metadata, and structured metadata
* **URLs**: Copy the original or optimized URL with one click

> **NOTE**: Assets delivered with [authenticated access control](control_access_to_media#authenticated_media_assets) are marked with a lock icon, and the extension uses a signed URL for previewing and copy actions.

![Asset Explorer](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1749821507/docs/vscode_extension_view.png "thumb: w_600,dpr_2, width:600, with_code:false, with_url:false, popup:true")

### Switching environments

If you work with multiple Cloudinary accounts or environments (such as development, staging, and production), you can easily switch between them.

1. Click **Switch Environment** on the home dashboard, or click the Cloudinary environment indicator in the VS Code status bar (it shows your current cloud name, for example `my-dev-cloud`).
2. Select a different environment from the dropdown list that appears.

The extension refreshes the asset tree to show assets from the newly selected environment. All operations (browsing, searching, uploading) now apply to the selected environment. Open preview and upload panels close when you switch, and upload presets are refetched for the new environment. When you reopen VS Code, the extension starts with the first environment listed in your configuration file.

This is particularly useful when you need to:

* Compare assets between environments
* Upload test assets to development without affecting production
* Verify that assets exist in production before referencing them in deployment-ready code
* Work on multiple client projects with different Cloudinary accounts

### Asking Docs AI

The Docs AI assistant lets you chat with the Cloudinary documentation without leaving your editor.

1. On the home dashboard, type a question in the **Ask Cloudinary AI** box, or click one of the suggested questions (for example, "How do I upload images?" or "Explain image transformations").
2. Read the answer in the dedicated Docs AI panel. Responses include **source citations** that link back to the relevant documentation.
3. Continue the conversation with follow-up questions.
4. Reopen earlier chats from the **recent conversations** list.

### Configuring AI tools

The **Configure AI Tools** feature installs Cloudinary agent skills and MCP server configuration into your project or globally, so your AI coding assistant can work with Cloudinary out of the box.

You can launch it from the **Configure AI Tools** action on the home dashboard, or by running **Cloudinary: Configure AI Tools** from the command palette. From the home dashboard's AI Tools panel you can:

1. Choose a **Platform**, such as Claude Code, Cursor, VS Code (Copilot), Windsurf, or another supported AI coding tool.
2. Choose a **Scope**:
   * **Project**: Install into the current workspace (committed with your project)
   * **Global**: Install into your home directory, available across all projects
3. Select which **Skills** and **MCP Servers** to install. The panel marks anything that's already configured.
4. Click **Apply**.

The available MCP servers are:

* **Cloudinary Asset Management**: Browse, upload, and manage media assets
* **Cloudinary Environment Config**: Configure upload presets, transformations, and settings
* **Cloudinary Structured Metadata**: Manage structured metadata fields and values
* **Cloudinary Analysis**: AI-powered image and video analysis
* **MediaFlows**: AI-powered media workflows and automation

For more on these servers and how to use them, see [Cloudinary AI agent tools and MCP servers](cloudinary_llm_mcp).

## Typical workflow

Here's how the extension integrates into a typical development session:

1. **Start building** an app that displays images or videos
2. **Browse assets** in the Library to see what's available
3. **Copy public IDs** directly into your code
4. **Upload assets** if needed without leaving your editor
5. **Preview assets** to verify they look correct
6. **Ask Docs AI** when you need a quick answer or example from the documentation
7. **Switch environments** to test against staging or production assets

All without opening a browser or switching contexts.

## Current limitations

The extension currently has some limitations:

* Filtering is limited to media type (images, videos, raw files)
* No drag-and-drop URL insertion directly into code editors
* Limited bulk operations (no multi-select for batch actions)
* No in-editor transformation builder or advanced transformation preview

We're actively developing the extension and plan to address these limitations based on user feedback.

## Feedback and contributions

The Cloudinary VS Code Extension is open source. We welcome your feedback and contributions:

* **GitHub repository**: [cloudinary/cloudinary-vscode-extension](https://github.com/cloudinary-devs/cloudinary-vscode)
* **Report issues**: [GitHub Issues](https://github.com/cloudinary-devs/cloudinary-vscode/issues)
* **Feature requests**: Use GitHub Issues with the "enhancement" label
* **Pull requests**: Contributions are welcome

## What's next

Future enhancements we're considering based on developer feedback:

* Direct URL insertion into code files with IntelliSense support
* Advanced transformation preview and editing
* Bulk asset operations (multi-select, batch tag management)
* Integration with popular framework tooling
* Asset metadata editing directly from VS Code
* Custom transformation templates

If these or other features would be valuable to your workflow, let us know through [GitHub Issues](https://github.com/cloudinary-devs/cloudinary-vscode/issues).

## Related resources

> **READING**:
>
> * [Cloudinary AI agent tools and MCP servers](cloudinary_llm_mcp) - AI-assisted Cloudinary operations and code generation

> * [Cloudinary CLI](cloudinary_cli) - Command-line interface for bulk operations and automation

> * [Upload API](image_upload_api_reference) - Programmatic upload capabilities

> * [Admin API](admin_api) - Asset management operations