--- layout: Conceptual title: Azure Cosmos DB Shell - Azure Cosmos DB | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/azure/cosmos-db/shell/overview uhfHeaderId: MSDocsHeader-NoSQL permissioned-type: public recommendations: true recommendation_types: - Training - Certification breadcrumb_path: ../../breadcrumb/azure-nosql/toc.json feedback_system: Standard feedback_product_url: https://feedback.azure.com/d365community/forum/3002b3be-0d25-ec11-b6e6-000d3a4f0858 feedback_help_link_url: /answers/tags/187/azure-cosmos-db/ feedback_help_link_type: get-help-at-qna ms.service: azure-cosmos-db ms.subservice: nosql ms.reviewer: mjbrown ms.author: sasinnat author: sajeetharan description: Learn about the Azure Cosmos DB Shell, a powerful command-line interface for interacting with Cosmos DB databases with bash-like commands and AI integration. ms.topic: overview ms.update-cycle: 180-days ms.date: 2026-10-19T00:00:00.0000000Z ai-usage: ai-assisted locale: en-us document_id: 5e3eee8e-a95d-4fb6-fdc6-6846c3a5f85e document_version_independent_id: 5e3eee8e-a95d-4fb6-fdc6-6846c3a5f85e updated_at: 2026-10-29T12:08:00.0000000Z original_content_git_url: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/live/azure/cosmos-db/shell/overview.md gitcommit: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/d544fbd677e5c098756dbf81dcc8b6ff167255c1/azure/cosmos-db/shell/overview.md git_commit_id: d544fbd677e5c098756dbf81dcc8b6ff167255c1 site_name: Docs depot_name: Learn.azure-nosql page_type: conceptual toc_rel: ../toc.json word_count: 615 asset_id: cosmos-db/shell/overview moniker_range_name: monikers: [] item_type: Content source_path: azure/cosmos-db/shell/overview.md cmProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/cd668c2f-f5b3-4573-8ad1-019570e3e2db - https://authoring-docs-microsoft.poolparty.biz/devrel/911a44a7-2f6c-477c-810f-dc8b7d425cce - https://authoring-docs-microsoft.poolparty.biz/devrel/a3955c7b-f5ee-420d-aff5-d7119738f38b spProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42 - https://authoring-docs-microsoft.poolparty.biz/devrel/14f2b9d5-6f06-45a8-ac5f-313eaa351153 - https://authoring-docs-microsoft.poolparty.biz/devrel/b31948f4-2f38-404b-ac93-c3c8c5b3ae33 platformId: 75eafd4a-38e5-723b-614d-310a785af218 --- # Azure Cosmos DB Shell - Azure Cosmos DB | Microsoft Learn 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](visual-studio-code) - **NuGet Package** - Install as .NET global tool - See: [Installation Guide](install) - **Self-Contained Binary** - Pre-built binaries for your platform - See: [Installation Guide](install) ## Quick start ```bash # 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](get-started). ## 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](https://www.nuget.org/packages/CosmosDBShell/1.0.213-preview) | | VS Code Extension | Latest | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) | | Self-Contained Binaries | 1.0.213-preview | Available for Windows, macOS, Linux | ## Documentation - [Installation Guide](install) - Install using your preferred method - [Quick Start Guide](get-started) - Get started in minutes - [Command Reference](command-reference) - Complete command documentation - [Model Context Protocol Setup](model-context-protocol-setup) - Enable AI integration - [Visual Studio Code Extension](visual-studio-code) - VS Code integration guide - [Troubleshooting Guide](troubleshooting) - Resolve common issues - [Security Best Practices](security) - Secure your credentials and data ## Support and feedback - [Report Issues](https://github.com) - Found a bug? - [Submit Feature Requests](https://github.com) - Have a feature idea? - [View Security Considerations](security) - 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](/en-us/training/support/mcp). For a compact guide index, use the [Shell documentation index (`llms.txt`)](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](/en-us/azure/cosmos-db/shell/model-context-protocol-setup)** Configure Shell MCP for authenticated database operations. > > **[Read as Markdown](/en-us/azure/cosmos-db/shell/overview?accept=text/markdown)** Open a text version to copy into your assistant. > > **[Ask ChatGPT](https://chatgpt.com/?hint=search&q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Foverview%20and%20explain%20Shell%20capabilities%20and%20requirements.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Explore Shell capabilities and requirements. > > **[Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Foverview%20and%20explain%20Shell%20capabilities%20and%20requirements.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** 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.