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.
Azure Cosmos DB Shell is a powerful, open-source command-line interface (CLI) that enables you to interact with your Azure Cosmos DB databases using intuitive bash-like commands. It features optional Model Context Protocol (MCP) server support for AI-powered automation and integrates seamlessly with VS Code through an extension.
Key features
- Bash-like Syntax: Familiar command structure with commands like
cd,ls,pwd,rm,mkdir - Database Operations: Create and manage databases and containers
- Data Manipulation: Query, insert, update, and delete documents
- Pipe Support: Chain commands together for powerful data transformations
- JSON Queries: Execute SQL queries with JSON output
- Scripting: Write and execute shell scripts for automated operations
- MCP Server Integration: Enable AI assistants to interact with your Cosmos DB resources
- VS Code Extension: Seamless integration with Visual Studio Code
- Open Source: Community-driven development with transparent contributions
System requirements
- Operating System: Windows, macOS (Intel and Apple Silicon), Linux (x64 and ARM)
- For NuGet Installation: .NET SDK 10.0 or later
- For VS Code Extension: VS Code 1.85 or later
- Authentication: Microsoft Entra ID, Managed Identity, or Account Keys
Installation options
Choose one of three installation methods:
VS Code Extension (Recommended)
- Install directly from VS Code Marketplace
- See: Visual Studio Code Extension Setup
NuGet Package
- Install as .NET global tool
- See: Installation Guide
Self-Contained Binary
- Pre-built binaries for your platform
- See: Installation Guide
Quick start
# Connect to your Cosmos DB account
cosmosdbshell
# Navigate to a database
> cd database_name
# List containers
> ls
# Query documents
> query "SELECT * FROM c WHERE c.name = 'John'"
For more examples, see the Quick Start Guide.
Use cases
- Development & Testing: Quick command-line access during development
- Database Administration: Manage databases, containers, and data
- Data Exploration: Query and explore your data interactively
- Automation: Use in scripts for automated database operations
- AI Integration: Enable AI assistants to work with your data via MCP
- Learning: Educational tool for learning Cosmos DB concepts
Release status
Azure Cosmos DB Shell is currently in private preview. This is a preview version for testing and feedback purposes only. Your feedback is valuable in helping us improve the tool.
Available distributions
| Package | Version | Location |
|---|---|---|
| NuGet Package | 1.0.213-preview | NuGet.org |
| VS Code Extension | Latest | VS Code Marketplace |
| Self-Contained Binaries | 1.0.213-preview | Available for Windows, macOS, Linux |
Documentation
- Installation Guide - Install using your preferred method
- Quick Start Guide - Get started in minutes
- Command Reference - Complete command documentation
- Model Context Protocol Setup - Enable AI integration
- Visual Studio Code Extension - VS Code integration guide
- Troubleshooting Guide - Resolve common issues
- Security Best Practices - Secure your credentials and data
Support and feedback
- Report Issues - Found a bug?
- Submit Feature Requests - Have a feature idea?
- View Security Considerations - Review security best practices
AI tools
Use these actions to explore Shell capabilities 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 for authenticated database operations.Read as Markdown
Open a text version to copy into your assistant.Ask ChatGPT
Explore Shell capabilities and requirements.Ask Claude
Explore Shell capabilities and requirements.
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.