Inspecting Local Data with Azure Cosmos DB Shell

Explore local data from the terminal, with the emulator as your development environment.

Azure Cosmos DB Shell gives me a direct way to work with my data from the terminal. I can navigate databases and containers, query documents, and read a specific item without opening the portal or adding temporary application code. That is useful while I am getting an application ready to ship. A value looks wrong, a document is missing, or I want to check one partition. Instead of guessing what was stored, I can inspect it.

The Azure Cosmos DB Linux Emulator provides the local environment for this walkthrough. In the previous post in this series, we used it to make local development and CI repeatable. This installment adds the shell so we can inspect that local data directly before deployment.

I am reusing FleetCharge‘s dispatch records as the example data. The focus is the shell: connect, navigate, inspect, query, and point-read. We are troubleshooting during development, not investigating a production incident.

https://devblogs.microsoft.com/cosmosdb/wp-content/uploads/sites/52/2026/10/cosmos-shell-walkthrough-captioned.mp4

Shell is the inspection tool for this walkthrough, but it is not required to run FleetCharge or its CI tests. Choose one of these installation methods.

The official installation guide includes a .NET global-tool option. This method requires the .NET SDK 10.0 or later. Install the tool and check its version:

dotnet tool install --global CosmosDBShell --prerelease cosmosdbshell --version

If you already installed the global tool for the previous post, skip the install command and check its version. Start the shell with:

cosmosdbshell

Download a self-contained binary

Alternatively, get a self-contained binary from the official releases. This option includes its runtime, so no separate .NET installation is needed. For this Windows x64 walkthrough, I used the 1.1.280-preview Windows x64 ZIP. Extract it and open PowerShell in the extracted directory containing CosmosDBShell.exe. Check the version and start the shell:

.\CosmosDBShell.exe --version .\CosmosDBShell.exe

For other platforms or a source build, follow the shell’s installation guidance and choose the matching release asset. The source-build path requires the .NET SDK; it is not an extra step in the ZIP-based path above. The examples below use commands verified with Shell 1.1.280-preview. The print <item-id> <partition-key> command reads one item; the application and its data model have not changed.

The emulator lets me try these operations locally, without connecting to a live Azure account. The FleetCharge sample provides the same seed records as the previous post. If you followed that walkthrough, reuse your checkout: no application code, fixture, schema, or CI workflow changes are required. We are adding an inspection tool, not building a new application.

The previous post used Git Bash; I am using PowerShell for the host commands below. That changes the terminal syntax, not the application. Commands inside Cosmos DB Shell are in separate text blocks; they are not PowerShell commands.

FleetCharge’s managed demo and CI commands start their own emulators with dynamically assigned ports. They clean up their resources when they finish. That is useful for tests, but I do not want my inspection environment to disappear halfway through this walkthrough.

As in the previous post, I use the sample’s direct-startup approach. If your own directly started emulator is still running, reuse it: skip docker run below and continue with the readiness check. If you chose different ports, use those ports consistently for readiness, seeding, and the shell connection.

Otherwise, start the emulator in one PowerShell terminal:

$image = "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest" docker run --rm --name fleetcharge-shell-local -p 127.0.0.1:8081:8081 -p 127.0.0.1:8080:8080 $image --protocol http

Leave that terminal running. The emulator’s standard ports are exposed unchanged: 8081 for the database endpoint and 8080 for readiness. Both are bound to loopback. If either port or the container name is already in use, check what owns it before continuing. Do not stop or reuse an unrelated container.

In a second PowerShell terminal, opened at the FleetCharge repository root, check readiness:

Invoke-RestMethod -Uri http://127.0.0.1:8080/ready

Wait for HTTP 200 with ready: true before seeding. If the emulator is still starting, check again rather than continuing after an error. Then install the locked dependencies, preserve any existing local settings, and explicitly select the endpoint and database for this session. These environment variables override the checkout’s existing .env settings, keeping the seed script and shell on the same endpoint without changing application code:

uv sync --locked if (-not (Test-Path .env)) { Copy-Item .env.example .env } $env:COSMOS_ENDPOINT = "http://127.0.0.1:8081" $env:COSMOS_DATABASE = "fleetchargetest-demo" uv run --locked python -m scripts.seed_cosmos

The seed command provisions the containers and writes the sample documents. Run it only against your own local demonstration environment: rerunning it upserts the fixture records and can replace changes you made to those records. The shell can now inspect those records directly. Neither FleetCharge’s API nor Ollama needs to be running for this walkthrough.

connect http://127.0.0.1:8081/

The shell recognizes this loopback emulator endpoint and selects the well-known emulator key and Gateway mode. Optionally, to display the current connection information, run connect without an argument. This is an inspection step, not a second connection:

connect

The connection information should show http://127.0.0.1:8081/ and Gateway. This is the database endpoint, not the readiness URL. Now I can start exploring:

ls

Figure 1. Confirm the local endpoint, then list the databases without leaving the terminal.

Find the FleetCharge database

At the account level, ls lists databases. The seed command created one named fleetchargetest-demo. Move into it, check the current path, and list its containers:

cd fleetchargetest-demo pwd ls

For this example, I want dispatchUpdates, the container holding the current pickup-bay information for each depot:

cd dispatchUpdates pwd

The current path is now:

/fleetchargetest-demo/dispatchUpdates

I can also navigate directly using the full path:

cd /fleetchargetest-demo/dispatchUpdates

Figure 2. Navigate from the account to FleetCharge’s dispatch data like moving through a filesystem.

Look at the data

Now that I am inside the container, I can inspect the items stored there. To return up to 10:

ls -m 10

That is a limit, not a request for the 10 newest items. This command does not establish a chronological order. For this tiny seeded container, I can also remove the limit:

ls -m 0

On a fresh seed, there are two dispatch documents:

Unlimited listing is convenient for two local sample documents, not a default I would carry over to a large container. Start with a limit or a narrower query.

This is useful while developing because I can see what is actually in Cosmos DB, rather than what I expected the application to write. No portal. No temporary endpoint. No debug code.

Listing documents is useful, but most of the time I am looking for something specific. Start with a basic query against this small container:

query "SELECT * FROM c"

Now narrow the results to one depot:

query "SELECT * FROM c WHERE c.depotId = 'SEA-01'"

On a fresh seed, that returns the Seattle dispatch document. Or return only the fields I care about:

query "SELECT c.id, c.depotId, c.updateId, c.pickupBay FROM c"

That last query projects four fields from both depots; it does not include the Seattle filter. The smaller result is easier to scan without the system metadata included by SELECT *. These are literal, interactive queries against known sample data. Application code should continue using parameterized queries for values supplied at runtime, as FleetCharge already does.

Sometimes I already know exactly which document I want. The dispatchUpdates container uses /depotId as its partition key. For Seattle, the item ID is current-dispatch and the partition-key value is SEA-01:

print current-dispatch SEA-01

The business fields in the result are shown below. This is an excerpt; the actual point-read output also includes Cosmos DB system metadata.

{ "id": "current-dispatch", "type": "dispatchUpdate", "depotId": "SEA-01", "updateId": "dispatch-001", "pickupBay": "BAY-2" }

For Portland:

print current-dispatch PDX-02

The corresponding excerpt is:

{ "id": "current-dispatch", "type": "dispatchUpdate", "depotId": "PDX-02", "updateId": "dispatch-099", "pickupBay": "BAY-99" }

Same item ID. Different partition key. Different document. For a point read, the item ID alone is not enough: the complete partition key is part of the address. The shell’s print command performs a point read, rather than querying the container to find a matching item. For FleetCharge, that makes it straightforward to compare the current dispatch document for two depots without querying every dispatch document.

The shell works much like navigating a filesystem. Move back one level and list the containers:

cd .. ls

Or jump directly back to the dispatch container:

cd /fleetchargetest-demo/dispatchUpdates

That sounds simple, but it matters when an application has several containers. I can move through the data model without reconnecting or rebuilding each command.

This is the part I like about putting the emulator and the shell together. The shell makes the stored data visible while I am building and testing. The emulator supplies the repeatable local environment behind it.

An application write looks unexpected. Open the shell. A local test fails because the stored document does not look right. Inspect the same document in the same test environment while it is still available. Need to check one partition without adding diagnostic code? Use a point read.

The workflow stays close to the application: Build -> Run -> Inspect -> Query -> Fix -> Run again

The command-line workflow also fits naturally into development containers and scripted tooling. Here it complements FleetCharge’s existing CI checks; it does not replace them or add a new CI gate.

The same shell commands work after an application changes the data. If I run the dispatch-feed example from the FleetCharge README, I can point-read the updated document and compare its updateId and pickupBay with what the application acknowledged. I do not need a separate inspection endpoint.

These are local checks during development, not a production incident-response procedure. The emulator does not prove production authentication, authorization, performance, throughput, or resiliency. Its well-known key is not a production credential, and successful local operations do not validate Azure access. Keep this HTTP setup on loopback.

FleetCharge itself accepts only loopback Cosmos endpoints and test-prefixed database names. It is intentionally not configured for deployment to a live account. Production readiness still needs the appropriate security, networking, deployment, monitoring, and workload validation.

With the local emulator running and the FleetCharge fixtures seeded, open Cosmos DB Shell and try:

connect http://127.0.0.1:8081/ ls cd fleetchargetest-demo ls cd dispatchUpdates pwd ls -m 10 query "SELECT * FROM c WHERE c.depotId = 'SEA-01'" print current-dispatch SEA-01 print current-dispatch PDX-02

That is enough to go from a local application environment to inspecting the data behind it without writing additional application code. When finished, in the repository terminal with the same Cosmos environment variables, remove only your demo database:

uv run --locked python -m scripts.cleanup_cosmos