Install Azure Cosmos DB Shell

Choose the Visual Studio Code extension for editor integration, a .NET global tool for terminal access, or a self-contained binary when you don't want to install .NET.

Option 1: Visual Studio Code extension

The Azure Cosmos DB extension includes a flow to install and launch the shell.

  1. Open Extensions in Visual Studio Code.

  2. Find and install Azure Cosmos DB, published by Microsoft. Its extension ID is ms-azuretools.vscode-cosmosdb.

  3. Open the Command Palette and run Launch Azure Cosmos DB Shell.

  4. Follow the installation or repair prompts if the shell isn't available.

  5. In the shell terminal, run:

    version
    

If you already installed the shell elsewhere, set cosmosDB.shell.path to the full executable path. Installing an extension-managed copy doesn't necessarily add cosmosdbshell to your operating-system PATH.

To install the extension offline, download its VSIX from the extension releases, then select Extensions > ... > Install from VSIX. Use a release compatible with your Visual Studio Code version.

For launch and MCP settings, see Use the shell in Visual Studio Code.

Option 2: .NET global tool

This method requires .NET SDK 10.0 or later. Installing only the runtime doesn't provide the dotnet tool command.

  1. Check the installed SDK from your operating-system terminal:

    dotnet --list-sdks
    
  2. Install the global tool:

    dotnet tool install --global CosmosDBShell
    
  3. Verify the executable:

    cosmosdbshell --version
    

Check CosmosDBShell on NuGet.org for available package versions.

Update the tool with:

dotnet tool update --global CosmosDBShell

Uninstall it with:

dotnet tool uninstall --global CosmosDBShell

Option 3: Self-contained binary

Self-contained archives include the .NET runtime. Download the matching platform and architecture from Azure/CosmosDBShell releases.

Operating system Runtime identifier
Windows x64 win-x64
Windows ARM64 win-arm64
macOS Intel osx-x64
macOS Apple Silicon osx-arm64
Linux x64 linux-x64
Linux ARM64 linux-arm64

Select the self-contained ZIP archive for your platform, not the framework-dependent archive with _fdd_ in its name. Framework-dependent distributions require a separately installed compatible .NET runtime.

  1. Download the archive and rename the downloaded file to cosmosdbshell.zip for the following commands.

  2. Extract the archive into a user-writable directory.

    On Windows, use PowerShell:

    Expand-Archive -Path .\cosmosdbshell.zip -DestinationPath "$HOME\cosmosdbshell"
    & "$HOME\cosmosdbshell\cosmosdbshell.exe" --version
    

    On macOS or Linux, use a terminal with unzip:

    mkdir -p "$HOME/cosmosdbshell"
    unzip cosmosdbshell.zip -d "$HOME/cosmosdbshell"
    chmod +x "$HOME/cosmosdbshell/cosmosdbshell"
    "$HOME/cosmosdbshell/cosmosdbshell" --version
    
  3. Optionally add the extraction directory to your user PATH. Open a new terminal after making a persistent PATH change.

  4. Launch the executable from that directory or by its full path. Once it is on PATH, run:

    cosmosdbshell
    

Verify the installation

Use cosmosdbshell --version in your operating-system terminal, or version inside an extension-launched shell. Then run help in the shell to discover the installed commands.

For release information, use the release notes. Avoid hardcoding an older archive or package version when following current command examples.

Troubleshoot installation

  • If dotnet can't find an appropriate SDK, install .NET SDK 10.0 or later before retrying the global-tool command.
  • If a global tool isn't found, check the tool installation result and ensure its directory is on PATH: %USERPROFILE%\.dotnet\tools on Windows or $HOME/.dotnet/tools on macOS and Linux.
  • If a downloaded binary can't run, check its operating system and CPU architecture. Check execute permission on macOS or Linux.
  • If the extension uses a different copy, check cosmosDB.shell.path and run version in its shell terminal.

AI tools

Use these actions to discuss installation with your assistant.

For documentation-only retrieval, use the Microsoft Learn MCP server. For a compact guide index, use the Shell documentation index (llms.txt). The index doesn't change crawler permissions or guarantee retrieval.

Shell MCP requires separate setup and can read or change data under the configured permissions, so review tool calls before approving them. Don't share credentials or sensitive data.

Connect your AI agent
Configure Shell MCP after installing the shell.

Read as Markdown
Open a text version to copy into your assistant.

Ask ChatGPT
Choose installation steps for your platform.

Ask Claude
Choose installation steps for your platform.

ChatGPT and Claude receive only the public article URL and a starter prompt. You might need to sign in. If retrieval fails, copy the Markdown text. These links don't configure database access.