Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
Open Extensions in Visual Studio Code.
Find and install Azure Cosmos DB, published by Microsoft. Its extension ID is
ms-azuretools.vscode-cosmosdb.Open the Command Palette and run Launch Azure Cosmos DB Shell.
Follow the installation or repair prompts if the shell isn't available.
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.
Check the installed SDK from your operating-system terminal:
dotnet --list-sdksInstall the global tool:
dotnet tool install --global CosmosDBShellVerify 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.
Download the archive and rename the downloaded file to
cosmosdbshell.zipfor the following commands.Extract the archive into a user-writable directory.
On Windows, use PowerShell:
Expand-Archive -Path .\cosmosdbshell.zip -DestinationPath "$HOME\cosmosdbshell" & "$HOME\cosmosdbshell\cosmosdbshell.exe" --versionOn 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" --versionOptionally add the extraction directory to your user
PATH. Open a new terminal after making a persistentPATHchange.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
dotnetcan'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\toolson Windows or$HOME/.dotnet/toolson 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.pathand runversionin 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.