Cosmosdb vnext emulator

Cosmos DB Shell for the local emulator

Stay shell-native: perform emulator administration and data operations through the bundled cosmoshell.sh.

1. Resolve the emulator

An emulator container is a running Docker container based on the official mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator image repository. Use the emulator container identified by the user or current project. Otherwise inspect running Docker containers and select the unique match; ask when none or several match.

When the task depends on image configuration, inspect the exact image behind the selected container:

image="$(docker inspect --format '{{.Config.Image}}' <emulator-container>)"
docker run --rm "$image" --help

Use this installed-image output for startup flags, defaults, environment-variable overrides, and the release version.

Before data operations, resolve the published health port and check readiness:

docker port <emulator-container> 8080
curl -fsS http://localhost:<published-health-port>/ready

Use /alive for liveness and /status for detailed health. If readiness fails, inspect docker logs --tail 100 <emulator-container>. Prefer health probes over matching log text.

Complete when: one running emulator container is identified and ready, or a specific readiness failure is reported.

2. Select the command

Use non-interactive execution for normal agent work:

docker exec <emulator-container> cosmoshell.sh -c '<command>'

The bundled cosmoshell.sh wrapper discovers the emulator endpoint and well-known key. Inspect the installed version or command syntax when needed:

docker exec <emulator-container> cosmoshell.sh --version
docker exec <emulator-container> cosmoshell.sh -c 'help <command>'

Cosmos DB Shell is stateful within one invocation. Enter the required database and container scope with cd in the same -c command or script before running a scoped operation.

Everything inside -c is Cosmos DB Shell syntax, not host-shell syntax. Use Cosmos DB Shell commands such as echo and its native pipes; keep host utilities outside the quoted command.

Choose the item-loading path based on the source and scale. Use inline mkitem commands for a small, explicitly known set of items. Use JSONL import when the user already has a data file or requests a file-based or bulk workflow. Do not create and copy a temporary JSONL file solely to insert a handful of sample items. When importing a host file, docker cp is expected because cosmoshell.sh reads paths inside the emulator container.

Use an interactive shell only when the user asks for one. For unfamiliar syntax, run help <command> through cosmoshell.sh before composing the operation.

Complete when: the selected Cosmos DB Shell command or script directly matches the requested operation.

3. Execute safely

These emulator capability limits are execution guardrails:

Requested capability	Emulator vNext status
Custom indexing policies or collection updates	No-op
Throughput, Request Units, or performance settings	Not implemented
Stored procedures, triggers, or user-defined functions	Not planned

For a request matching this table, run no command. Report the requested capability, its status, and that emulator state is unchanged. A CosmosDBShell command existing or returning success does not override the emulator limitation. For other configuration or server-side operations, check the current feature-support matrix before execution.

For an inspection or read-only request, build the command plan only from help, pwd, ls, cd, query, and info. Use this query shape:

docker exec <emulator-container> cosmoshell.sh -c 'cd <database>; cd <container>; query "<sql>"'

Before execution, check every top-level CosmosDBShell command token against the read-only set; revise any command containing another token. If the requested resource is absent, report that result without creating, repairing, or seeding anything.

Before rm, rmdb, rmcon, or another delete operation, inspect that command's current help, show the intended cosmoshell.sh command, state the exact target, and obtain the user's confirmation. For non-interactive -c execution, use the documented force/confirmation-bypass argument only after the user confirms.

Keep emulator operations shell-native even if a command fails. Inspect command help, correct the Cosmos DB Shell invocation, or report an emulator limitation instead of substituting another client.

Complete when: every requested operation has either succeeded through cosmoshell.sh or has a specific reported failure.

4. Verify

Read back mutations with the smallest relevant ls, query, info, or command-specific inspection. Report the executed command and ground the result in its output.

The task is complete only when every successful mutation is verified and every failure identifies the command that failed.

Examples

Use the creation example only when the task asks to create sample data. For read-only tasks, substitute existing resource names and leave missing resources unchanged.

Create sample data and verify it

docker exec <emulator-container> cosmoshell.sh -c 'mkdb SampleStore'
docker exec <emulator-container> cosmoshell.sh -c \
  'mkcon Products /category --database=SampleStore'
docker exec <emulator-container> cosmoshell.sh -c \
  "mkitem '{\"id\":\"p1\",\"category\":\"books\",\"name\":\"Notebook\"}' --database=SampleStore --container=Products"
docker exec <emulator-container> cosmoshell.sh -c \
  "mkitem '{\"id\":\"p2\",\"category\":\"electronics\",\"name\":\"Keyboard\"}' --database=SampleStore --container=Products"
docker exec <emulator-container> cosmoshell.sh -c \
  'query "SELECT c.id, c.category, c.name FROM c ORDER BY c.id" --database=SampleStore --container=Products'

Explore existing databases and containers

docker exec <emulator-container> cosmoshell.sh -c \
  'pwd; ls; cd SampleStore; pwd; ls; cd Products; pwd; info; ls -max=5'

Query existing data

docker exec <emulator-container> cosmoshell.sh -c \
  "query \"SELECT TOP 5 c.id, c.name FROM c WHERE c.category = 'books' ORDER BY c.name\" --database=SampleStore --container=Products"

Validate a file-based JSONL import

products.jsonl:

{"id":"p3","category":"books","name":"Pen"}
{"id":"p4","category":"electronics","name":"Mouse"}

docker cp products.jsonl <emulator-container>:/tmp/products.jsonl
docker exec <emulator-container> cosmoshell.sh -c \
  'import /tmp/products.jsonl --dry-run --database=SampleStore --container=Products'

Bulk import, export, and re-import JSONL data

docker cp products.jsonl <emulator-container>:/tmp/products.jsonl
docker exec <emulator-container> cosmoshell.sh -c \
  'import /tmp/products.jsonl --mode=upsert --database=SampleStore --container=Products; export /tmp/products-export.jsonl --force --database=SampleStore --container=Products'
docker cp <emulator-container>:/tmp/products-export.jsonl ./products-export.jsonl

docker exec <emulator-container> cosmoshell.sh -c \
  'mkcon ProductsCopy /category --database=SampleStore'
docker exec <emulator-container> cosmoshell.sh -c \
  'import /tmp/products-export.jsonl --mode=upsert --database=SampleStore --container=ProductsCopy; query "SELECT c.id, c.category, c.name FROM c ORDER BY c.id" --database=SampleStore --container=ProductsCopy'

Run a parameterized .csh script

load-data.csh:

# $1 = database, $2 = container, $3 = data file
import $3 --mode=upsert --database=$1 --container=$2
query "SELECT c.id, c.category, c.name FROM c ORDER BY c.id" --database=$1 --container=$2

docker cp products.jsonl <emulator-container>:/tmp/products.jsonl
docker cp load-data.csh <emulator-container>:/tmp/load-data.csh

docker exec <emulator-container> cosmoshell.sh -c \
  'mkcon ScriptedProducts /category --database=SampleStore'
docker exec <emulator-container> cosmoshell.sh -c \
  '/tmp/load-data.csh SampleStore ScriptedProducts /tmp/products.jsonl'

# Run it again to demonstrate repeatability.
docker exec <emulator-container> cosmoshell.sh -c \
  '/tmp/load-data.csh SampleStore ScriptedProducts /tmp/products.jsonl'

Boundaries

• Target only the local Linux emulator vNext; do not connect this skill to a live Azure account.
• Use the CLI execution path, not the Cosmos DB Shell MCP server.

Sources

• Linux emulator vNext
• Cosmos DB Shell overview
• Cosmos DB Shell command documentation