---
layout: Conceptual
title: Azure Cosmos DB Shell Quick Start - Azure Cosmos DB | Microsoft Learn
canonicalUrl: https://learn.microsoft.com/en-us/azure/cosmos-db/shell/get-started
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: Quick start guide with examples to get you started with Azure Cosmos DB Shell in minutes.
ms.topic: how-to
ms.date: 2026-10-19T00:00:00.0000000Z
ai-usage: ai-assisted
locale: en-us
document_id: 574bdba5-1bf4-75c5-d806-edfc8875ba5f
document_version_independent_id: 574bdba5-1bf4-75c5-d806-edfc8875ba5f
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/get-started.md
gitcommit: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/d544fbd677e5c098756dbf81dcc8b6ff167255c1/azure/cosmos-db/shell/get-started.md
git_commit_id: d544fbd677e5c098756dbf81dcc8b6ff167255c1
site_name: Docs
depot_name: Learn.azure-nosql
page_type: conceptual
toc_rel: ../toc.json
word_count: 1246
asset_id: cosmos-db/shell/get-started
moniker_range_name: 
monikers: []
item_type: Content
source_path: azure/cosmos-db/shell/get-started.md
cmProducts:
- https://authoring-docs-microsoft.poolparty.biz/devrel/cd668c2f-f5b3-4573-8ad1-019570e3e2db
spProducts:
- https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42
platformId: 0923d0cc-86f2-2e69-1923-1de2fac7211c
---

# Azure Cosmos DB Shell Quick Start - Azure Cosmos DB | Microsoft Learn

Get started with Azure Cosmos DB Shell in just a few minutes with these practical examples.

## Prerequisites

- Azure Cosmos DB Shell installed ([Installation Guide](install))
- Azure Cosmos DB account
- Authentication configured (Microsoft Entra ID, Managed Identity, or Account Keys)

## Launch the shell

```bash
cosmosdbshell
```

You'll see a prompt:

```
CS >
```

## Connect to your account

When launched without connection arguments, Azure Cosmos DB Shell starts in a disconnected state. Use the `connect` command to authenticate and connect to an account. The shell automatically selects the appropriate credential type based on the arguments you provide.

**Use Microsoft Entra ID** (recommended):

```bash
CS > connect https://<account-name>.documents.azure.com:443/ --tenant=<tenant-id>
```

This starts the browser sign-in flow. You can optionally add `--hint=user@contoso.com` to pre-fill the login.

**Use Managed Identity** (production):

```bash
CS > connect https://<account-name>.documents.azure.com:443/ --managed-identity=<client-id>
```

For system-assigned managed identity, use the endpoint-only form — `DefaultAzureCredential` includes `ManagedIdentityCredential` in its chain automatically:

```bash
CS > connect https://<account-name>.documents.azure.com:443/
```

**Use Account Key** (development/testing):

```bash
CS > connect "AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;"
```

Note

Quote the connection string. A connection string contains `;`, which the shell treats as a command separator.

## Basic navigation

### View your account endpoint

```bash
CS > endpoint
```

### List databases

```bash
CS > ls
```

Output:

```
database1
database2
mydb
```

### Navigate to a database

```bash
CS > cd mydb
CS >
```

### List containers in database

```bash
CS > ls
```

Output:

```
users
products
orders
```

### Navigate to a container

```bash
CS > cd users
CS >
```

### Show current path

```bash
CS > pwd
```

Output:

```
/mydb/users
```

## Basic operations

### Create database

```bash
CS > mkdb mynewdb
```

### Create container

```bash
CS > mkcon mycontainer -pk /id
```

(Creates container with partition key `/id`)

### Query documents

```bash
CS > query "SELECT * FROM c WHERE c.status = 'active'"
```

Output:

```json
{
  "id": "user1",
  "name": "Alice",
  "status": "active"
}
{
  "id": "user2", 
  "name": "Bob",
  "status": "active"
}
```

### Count documents

```bash
CS > query "SELECT COUNT(*) FROM c"
```

### Insert document

```bash
CS > create item {"id": "user3", "name": "Charlie", "status": "active"}
```

### Update document

```bash
CS > update {"id": "user1", "name": "Alice", "status": "inactive"}
```

### Delete document

```bash
CS > rm user1
```

### Delete container

```bash
CS > rmcon users
```

### Delete database

```bash
CS > rmdb mydb
```

## Piping commands

Combine commands to create powerful workflows.

### Query and count

```bash
CS > query "SELECT * FROM c" | jq 'length'
```

### Filter results with jq

```bash
CS > query "SELECT * FROM c" | jq '.[] | select(.status == "active")'
```

### Extract specific fields

```bash
CS > query "SELECT * FROM c" | jq '.[] | {id, name}'
```

### Transform and output

```bash
CS > query "SELECT * FROM c" | jq '.[] | .name' | tr '\n' ','
```

## Shell scripts

Create a script file for automated operations.

### Example script: `batch_operations.sh`

```bash
#!/bin/bash

# Connect to Cosmos DB Shell
cosmosdbshell << 'EOF'
cd mydb
cd users

# Insert multiple documents
create item {"id": "user10", "name": "David", "status": "active"}
create item {"id": "user11", "name": "Eve", "status": "inactive"}
create item {"id": "user12", "name": "Frank", "status": "active"}

# Query and count
query "SELECT COUNT(*) as count FROM c"

# Exit
exit
EOF
```

### Run script

```bash
bash batch_operations.sh
```

## Filtering and searching

### Find documents with specific criteria

```bash
CS > query "SELECT * FROM c WHERE c.age > 30 AND c.status = 'active'"
```

### Search in arrays

```bash
CS > query "SELECT * FROM c WHERE ARRAY_CONTAINS(c.tags, 'vip')"
```

### Aggregate results

```bash
CS > query "SELECT c.status, COUNT(*) as count FROM c GROUP BY c.status"
```

## Export and import

### Export data to JSON

```bash
CS > query "SELECT * FROM c" > users_export.json
```

The exported file wraps the documents in an `items` envelope:

```json
{
  "items": [
    { "id": "user1", "pk": "tenantA", "name": "Alice", "status": "active",
      "_rid": "...", "_self": "...", "_etag": "...", "_attachments": "...", "_ts": 1730000000 },
    { "id": "user2", "pk": "tenantA", "name": "Bob", "status": "active",
      "_rid": "...", "_self": "...", "_etag": "...", "_attachments": "...", "_ts": 1730000001 }
  ]
}
```

### Export to CSV-like format

```bash
CS > query "SELECT * FROM c" | jq -r '.id, .name, .status' | paste -sd, > users.csv
```

### Import a bare JSON array

The `create item` command (alias `mkitem`) accepts either a single JSON object or a top-level JSON array. Use this form when you control the input file and can produce a clean array of documents.

Sample `users_import.json`:

```json
[
  { "id": "user10", "pk": "tenantA", "name": "David", "status": "active" },
  { "id": "user11", "pk": "tenantA", "name": "Eve",   "status": "inactive" },
  { "id": "user12", "pk": "tenantB", "name": "Frank", "status": "active" }
]
```

Import it by piping the file into `mkitem`:

```bash
CS > cat users_import.json | mkitem
```

Add `--force` (alias `--upsert`) to replace existing items instead of failing on `id` conflicts:

```bash
CS > cat users_import.json | mkitem --force
```

### Import a previously exported query result

A file produced by `query "SELECT * FROM c" > users_export.json` is **not** a bare array — it has the `{ "items": [ ... ] }` wrapper shown above and the documents still contain Cosmos system fields (`_rid`, `_self`, `_etag`, `_attachments`, `_ts`) that must not be sent back on insert.

Use `jq` to unwrap the array and strip system fields before piping to `mkitem`:

```bash
CS > cat users_export.json \
  | jq '[.items[] | del(._rid, ._self, ._etag, ._attachments, ._ts)]' \
  | mkitem --force --db=mydb --con=users
```

What each step does:

- `.items[]` unwraps the envelope and streams each document.
- `del(...)` removes the read-only Cosmos system fields.
- `[ ... ]` re-collects the results into the top-level array `mkitem` expects.
- `--force` makes the import idempotent (re-running replaces existing items).
- `--db` / `--con` target the destination explicitly so the import works regardless of your current shell location.

`mkitem` iterates the array sequentially and prints a summary with the number of items created or replaced and the total RU charge. Per-item failures (for example, an `id` conflict without `--force`) are reported inline but do not stop the import.

## Tips and best practices

### Use aliases for common commands

```bash
# Add to your shell profile
alias cosmosdb='cosmosdbshell'
```

### Tab completion

- Use Tab to auto-complete database and container names
- Press Tab twice to see all available options

### Command history

- Arrow up/down to navigate command history
- Ctrl+R to search command history

### Formatting output

```bash
# Pretty-print JSON
CS > query "SELECT * FROM c" | jq .

# Compact output
CS > query "SELECT * FROM c" | jq -c .
```

### Performance tips

- **Use partition key in queries** for faster results:

    ```bash
    CS > query "SELECT * FROM c WHERE c.id = 'user1'"
    ```
- **Limit result set** for large queries:

    ```bash
    CS > query "SELECT TOP 100 * FROM c"
    ```
- **Use projections** to reduce data transfer:

    ```bash
    CS > query "SELECT c.id, c.name FROM c"
    ```

## Common workflows

### Bulk insert from file

```bash
CS > jq -r '.[]' data.json | while read line; do
  create $line
done
```

### Backup container

```bash
CS > query "SELECT * FROM c" > backup_users.json
```

### Verify data migration

```bash
CS > query "SELECT COUNT(*) FROM c" 
CS > query "SELECT COUNT(*) FROM c"
```

## AI tools

Use these actions to discuss your first Shell session 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/get-started?accept=text/markdown)** Open a text version to copy into your assistant.
> 
> **[Ask ChatGPT](https://chatgpt.com/?hint=search&amp;q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Fget-started%20and%20help%20me%20plan%20a%20first%20Shell%20session.%20Explain%20commands%20before%20suggesting%20data%20changes.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Plan a first session and understand each command.
> 
> **[Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Fget-started%20and%20help%20me%20plan%20a%20first%20Shell%20session.%20Explain%20commands%20before%20suggesting%20data%20changes.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Plan a first session and understand each command.

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.