Azure Cosmos DB Shell command reference

Applies to: ✅ NoSQL

Complete reference guide for all Azure Cosmos DB Shell commands.

Commands for navigating databases and containers.

`cd` - Change directory

Navigate to a database or container.

Syntax:

cd <path>

Examples:

# Navigate to a database
CS > cd mydb
# Navigate to a container
CS > cd users
# Go back one level
CS > cd ..
# Navigate to root
CS > cd /
CS >

`ls` - List

List databases or containers in current location.

Syntax:

ls [options]

Options:

-l: Long format with details
-h: Human-readable sizes

Examples:

# List databases
CS > ls

# List containers with details
CS > ls -l

# List containers in human-readable format
CS > ls -h

`pwd` - Print working directory

Show the current path.

Syntax:

pwd

Examples:

CS > pwd
/mydb/users

`endpoint` - Show endpoint

Display the current Cosmos DB account endpoint.

Syntax:

endpoint

Examples:

CS > endpoint
https://myaccount.documents.azure.com:443/

Database management commands

Commands for creating and managing databases.

`mkdb` - Make database

Create a new database.

Syntax:

mkdb <database_name> [options]

Options:

--throughput <RU/s>: Provisioned throughput
--autoscale <max_RU/s>: Autoscale max throughput

Examples:

# Create database with default settings
CS > mkdb mydb

# Create database with provisioned throughput
CS > mkdb mydb --throughput 400

# Create database with autoscale
CS > mkdb mydb --autoscale 4000

`rmdb` - Remove database

Delete a database and all its contents.

Syntax:

rmdb <database_name> [--force]

Options:

--force: Skip confirmation prompt

Examples:

# Delete database (with confirmation)
CS > rmdb tempdb

# Delete database without confirmation
CS > rmdb tempdb --force

Container management commands

Commands for creating and managing containers.

`mkcon` - Make container

Create a new container.

Syntax:

mkcon <container_name> -pk <partition_key> [options]

Options:

-pk, --partition-key: Partition key path (required)
--throughput <RU/s>: Provisioned throughput
--autoscale <max_RU/s>: Autoscale max throughput
--ttl <seconds>: Time-to-live in seconds
--unique-key <path>: Unique constraint path

Examples:

# Create container with partition key
CS > mkcon users -pk /id

# Create with provisioned throughput
CS > mkcon users -pk /id --throughput 400

# Create with autoscale
CS > mkcon users -pk /id --autoscale 4000

# Create with TTL
CS > mkcon users -pk /id --ttl 86400

# Create with unique key
CS > mkcon users -pk /id --unique-key /email

`rmcon` - Remove container

Delete a container.

Syntax:

rmcon <container_name> [--force]

Options:

--force: Skip confirmation prompt

Examples:

# Delete container (with confirmation)
CS > rmcon tempcontainer

# Delete without confirmation
CS > rmcon tempcontainer --force

Data manipulation commands

Commands for querying and managing data.

`query` - Execute query

Execute a SQL query against a container.

Syntax:

query "<SQL_query>" [options]

Options:

--partition-key <value>: Specify partition key for targeted query
--max-items <count>: Maximum items to return
--continuation-token <token>: Continuation token for pagination

Examples:

# Query all documents
CS > query "SELECT * FROM c"

# Query with filter
CS > query "SELECT * FROM c WHERE c.status = 'active'"

# Query with partition key (faster)
CS > query "SELECT * FROM c WHERE c.id = 'user1'" --partition-key user1

# Query with limit
CS > query "SELECT TOP 10 * FROM c"

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

# Join query
CS > query "SELECT c.id, c.name, o.orderId FROM c JOIN o IN c.orders"

`create` - Create document

Insert a new document.

Syntax:

create item <JSON_document>

Examples:

# Create simple document
CS > create item {"id": "user1", "name": "Alice"}

# Create nested document
CS > create item {"id": "user2", "name": "Bob", "address": {"city": "Seattle", "country": "USA"}}

# Create with array
CS > create item {"id": "user3", "name": "Charlie", "tags": ["vip", "premium"]}

`update` - Update document

Update an existing document.

Syntax:

update <JSON_document>

Examples:

# Update document
CS > update {"id": "user1", "name": "Alice", "status": "active"}

# Partial update (with JSON merge semantics)
CS > update {"id": "user1", "status": "inactive"}

`rm` - Remove document

Delete a document.

Syntax:

rm <document_id> [--partition-key <value>]

Options:

--partition-key <value>: Specify partition key for faster deletion

Examples:

# Delete document
CS > rm user1

# Delete with partition key
CS > rm user1 --partition-key user1

`get` - Get document

Retrieve a specific document by ID.

Syntax:

get <document_id> [--partition-key <value>]

Options:

--partition-key <value>: Specify partition key for faster retrieval

Examples:

# Get document
CS > get user1

# Get with partition key
CS > get user1 --partition-key user1

Utility commands

General utility commands.

`jq` - JSON processing

Process JSON output using jq syntax.

Syntax:

<command> | jq '<jq_filter>'

Examples:

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

# Extract specific fields
CS > query "SELECT * FROM c" | jq '.[] | {id, name}'

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

# Transform data
CS > query "SELECT * FROM c" | jq '[.[] | {id, name}]'

`echo` - Display text

Output text to console.

Syntax:

echo "<text>"

Examples:

CS > echo "Starting operations..."
Starting operations...

`help` - Show help

Display help information.

Syntax:

help [command]

Examples:

# General help
CS > help

# Help for specific command
CS > help query

# Help for container commands
CS > help mkcon

`version` - Show version

Display the shell version.

Syntax:

version

Examples:

CS > version
Azure Cosmos DB Shell 1.0.213-preview

`exit` - Exit shell

Exit the Cosmos DB Shell.

Syntax:

exit

Examples:

CS > exit

Command chaining and piping

Commands can be chained using pipes (|) and redirects.

Pipe to `jq`

CS > query "SELECT * FROM c" | jq '.[]'

Pipe to file

CS > query "SELECT * FROM c" > output.json

Pipe to external command

CS > query "SELECT * FROM c" | grep "active"

Combine multiple operations

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

JSON path expressions

Use JSON path expressions in queries for advanced filtering.

Examples:

# Query nested properties
CS > query "SELECT c.address.city FROM c"

# Array operations
CS > query "SELECT * FROM c WHERE ARRAY_CONTAINS(c.tags, 'vip')"

# String functions
CS > query "SELECT * FROM c WHERE STARTSWITH(c.name, 'A')"

# Numeric functions
CS > query "SELECT * FROM c WHERE c.age > 30"

Connection commands

`connect` - Connect to account

Switch to a different Cosmos DB account.

Syntax:

connect <connection_string|endpoint> [--tenant=<tenant-id>] [--managed-identity=<client-id>] [--hint=<email>]

Credential selection:

The credential type is determined automatically based on the arguments provided. The options --tenant, --managed-identity, and connection strings with AccountKey are mutually exclusive — provide only one. If multiple are specified, the shell uses the first match in this precedence order:

Connection string with AccountKey: Account key
--managed-identity: Managed Identity
--tenant: Microsoft Entra ID (Interactive Browser)
Endpoint only (no additional arguments): DefaultAzureCredential

Examples:

# Connect with Entra ID (interactive browser)
CS > connect https://myaccount.documents.azure.com:443/ --tenant=<tenant-id>

# Connect with account key (quote the connection string)
CS > connect "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=<key>;"

CLI startup options

All connect options are also available as CLI startup arguments with a --connect- prefix. Use these to authenticate when launching the shell from your terminal:

Syntax:

cosmosdbshell --connect <endpoint> [--connect-tenant=<tenant-id>] [--connect-managed-identity=<client-id>] [--connect-subscription=<subscription-id>] [--connect-resource-group=<resource-group>]

Examples:

# Launch with Entra ID authentication
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-tenant=<tenant-id>

# Launch with managed identity
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-managed-identity=<client-id>

# Launch with explicit ARM context
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-tenant=<tenant-id> --connect-subscription=<subscription-id> --connect-resource-group=<resource-group>

Best practices

Use partition keys for faster queries
Limit result sets with TOP or --max-items
Use projections to reduce data transfer
Chain commands with pipes for complex operations
Use jq for JSON processing and formatting
Save complex queries in script files

AI tools

Use these actions to look up Shell commands 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
Find command syntax and identify data-changing operations.

Ask Claude
Find command syntax and identify data-changing operations.

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.

Feedback

Was this page helpful?

Last updated on 2026-10-29

Azure Cosmos DB Shell command reference

Navigation commands

cd - Change directory

ls - List

pwd - Print working directory

endpoint - Show endpoint

Database management commands

mkdb - Make database

rmdb - Remove database

Container management commands

mkcon - Make container

rmcon - Remove container

Data manipulation commands

query - Execute query

create - Create document

update - Update document

rm - Remove document

get - Get document

Utility commands

jq - JSON processing

echo - Display text

help - Show help

version - Show version

exit - Exit shell

Command chaining and piping

Pipe to jq

Pipe to file

Pipe to external command

Combine multiple operations

JSON path expressions

Connection commands

connect - Connect to account

CLI startup options

Best practices

AI tools

Related content

Feedback

Additional resources

`cd` - Change directory

`ls` - List

`pwd` - Print working directory

`endpoint` - Show endpoint

`mkdb` - Make database

`rmdb` - Remove database

`mkcon` - Make container

`rmcon` - Remove container

`query` - Execute query

`create` - Create document

`update` - Update document

`rm` - Remove document

`get` - Get document

`jq` - JSON processing

`echo` - Display text

`help` - Show help

`version` - Show version

`exit` - Exit shell

Pipe to `jq`

`connect` - Connect to account