Command-line and PowerShell reference for Windows (local) emulator

Article
09/14/2024

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

The Azure Cosmos DB emulator provides a local environment that emulates the Azure Cosmos DB service for local development purposes. After installing the emulator, you can control the emulator with command line and PowerShell commands. This article describes how to use the command-line and PowerShell commands to start and stop the emulator, configure options, and perform other operations. You have to run the commands from the installation location.

Important

This article only includes command-line arguments for the Windows local emulator.

Manage the emulator with command-line syntax

Microsoft.Azure.Cosmos.Emulator.exe 
    [/Shutdown] [/DataPath] [/Port] [/MongoPort] 
    [/DirectPorts] [/Key] [/EnableRateLimiting] 
    [/DisableRateLimiting] [/NoUI] [/NoExplorer] 
    [/EnableMongoDbEndpoint] 
    [/?]

To view the list of parameters, type Microsoft.Azure.Cosmos.Emulator.exe /? at the command prompt.

Parameter	Description	Example Command
[No arguments]	Starts up the emulator with default settings.	Microsoft.Azure.Cosmos.Emulator.exe
[Help]	Displays the list of supported command-line arguments.	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	Gets the status of the emulator. Each exit code indicates a status: `1` = Starting, `2` = Running, and `3` = Stopped. A negative exit code indicates that an error occurred. No other output is produced.	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	Shuts down the emulator.	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	Specifies the path in which to store data files. The default value is `%LocalAppdata%\CosmosDBEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	Specifies the port number to use for the emulator. The default value is `8081`.	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	Specifies the port number to use for the compute interop gateway service. The gateway's HTTP endpoint probe port is calculated as `ComputePort + 79`. Hence, `ComputePort` and `ComputePort + 79` must be open and available. The default value is `8900`.	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	Enables API for MongoDB version 3.2.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	Enables API for MongoDB version 3.6.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	Enables API for MongoDB version 4.0.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	Specifies the port number to use for API for MongoDB. Default value is `10255`.	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Enables API for Apache Cassandra.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Specifies the port number to use for the API for Cassandra endpoint. Default value is `10350`.	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Enables API for Apache Gremlin.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Port number to use for the API for Apache Gremlin Endpoint. Default value is `8901`.	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Enables API for Table.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	Port number to use for the API for Table Endpoint. Default value is `8902`.	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	Read authorization key from the specified file. Use the `/GenKeyFile` option to generate a keyfile.	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	Recursively removes all the files in the specified path. If you don't specify a path, it defaults to `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Start collecting debug trace logs using LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Stop collecting debug trace logs using LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Start collecting debug trace logs using Windows Performance Recording tool.	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Stop collecting debug trace logs using Windows Performance Recording tool.	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	By default the emulator regenerates its self-signed TLS/SSL certificate, if the certificate's SAN doesn't include the emulator host's domain name, local IP address ([v4]), `localhost`, and `127.0.0.1`. With this option, the emulator instead fails at startup. You should then use the `/GenCert` option to create and install a new self-signed TLS/SSL certificate.	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	Generate and install a new self-signed TLS/SSL certificate. optionally including a comma-separated list of extra Domain Name System (DNS) names for accessing the emulator over the network.	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	Specifies the ports to use for direct connectivity. Defaults are `10251`, `10252`, `10253`, and `10254`.	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	Authorization key for the emulator. Key must be the base-64 encoding of a 64-byte vector.	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	Specifies that request rate limiting behavior is enabled.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	Specifies that request rate limiting behavior is disabled.	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	Don't show the emulator user interface.	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	Don't show data explorer on startup.	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	Specifies the maximum number of partitioned containers. For more information, see change the number of containers. The default value is `25`. The maximum allowed is `250`.	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	Specifies the default number of partitions for a partitioned container. The default value is `25`.	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	Enables access to the emulator over a network. You must also pass `/Key=<key_string>` or /`KeyFile=<file_name>` to enable network access.	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	Don't adjust firewall rules when `/AllowNetworkAccess` option is used.	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	Generate a new authorization key and save to the specified file. The generated key can be used with the `/Key` or `/KeyFile` options.	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	Set the default consistency level for the account. The default value is Session.	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	Show the help message.

Manage the emulator with PowerShell cmdlets

The emulator comes with a PowerShell module to start, stop, uninstall, and retrieve the status of the service. Run the following cmdlet to use the PowerShell module:

Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"

Or place the PSModules directory on your PSModulePath and import it as shown in the following command:

$env:PSModulePath += ";$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules"
Import-Module Microsoft.Azure.CosmosDB.Emulator

Here's a summary of the commands for controlling the emulator from PowerShell:

`Get-CosmosDbEmulatorStatus`

Gets the status of the emulator. Returns one of these ServiceControllerStatus values:

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

If an error is encountered, no value is returned.

Syntax

Get-CosmosDbEmulatorStatus 
    [[-AlternativeInstallLocation] <String>] 
    [<CommonParameters>]

Parameters

Name	Type	Description
`AlternativeInstallLocation`	`String`

Examples

Get the status of an emulator installed in the D:\SomeFolder\AzureCosmosDBEmulator folder.

@parameters = {
    AlternativeInstallLocation = "D:\SomeFolder\AzureCosmosDBEmulator"
}
Get-CosmosDbEmulatorStatus @parameters

`Start-CosmosDbEmulator`

Starts the emulator on the local computer. By default, the command waits until the emulator is ready to accept requests. Use the -NoWait option, if you wish the cmdlet to return as soon as it starts the emulator. Use the parameters of Start-CosmosDbEmulator to specify options, such as the NoSQL port, direct port, and MongoDB port numbers.

Syntax

Start-CosmosDbEmulator [-AllowNetworkAccess]
    [-AlternativeInstallLocation <String>] [-CassandraPort <UInt16>]
    [-ComputePort <UInt16>] [-Consistency <String>] [-Credential
    <PSCredential>] [-DataPath <String>] [-DefaultPartitionCount
    <UInt16>] [-DirectPort <UInt16[]>] [-EnableMongoDb]
    [-EnableCassandra] [-EnableGremlin] [-EnableTable]
    [-EnableSqlCompute] [-EnablePreview]
    [-FailOnSslCertificateNameMismatch] [-GremlinPort <UInt16>]
    [-TablePort <UInt16>] [-SqlComputePort <UInt16>] [-Key <String>]
    [-MongoPort <UInt16>] [-MongoApiVersion <String>] [-NoFirewall]
    [-NoTelemetry] [-NoUI] [-NoWait] [-PartitionCount <UInt16>] [-Port
    <UInt16>] [-SimulateRateLimiting] [-Timeout <UInt32>] [-Trace]
    [<CommonParameters>]

Parameters

Name	Type	Description
`AllowNetworkAccess`	`SwitchParameter`	Allow access from all IP Addresses assigned to the emulator's host. You must also specify a value for Key or KeyFile to allow network access.
`AlternativeInstallLocation`	`String`	Alternative location path to the emulator executable.
`CassandraPort`	`UInt16`	Port number to use for the API for Cassandra. The default port is `10350`.
`ComputePort`	`UInt16`	Port to use for the compute interop gateway service. The gateway's HTTP endpoint probe port is calculated as `ComputePort + 79`. Hence, `ComputePort` and `ComputePort + 79` must be open and available. The default ports are `8900`, `8979`.
`Consistency`	`String`	Sets the default consistency level for the emulator to Session, Strong, Eventual, or BoundedStaleness. The default level is Session.
`Credential`	`PSCredential`	Specifies a user account that has permission to perform this action. Use a username, such as `User01` or `Domain01\User01`, or enter a `PSCredential` object, such as one from the `Get-Credential` cmdlet. By default, the cmdlet uses the credentials of the current user.
`DataPath`	`String`	Path to store data files. The default location for data files is `$env:LocalAppData\CosmosDbEmulator`.
`DefaultPartitionCount`	`UInt16`	The number of partitions to reserve per partitioned collection. The default is 25, which is the same as default value of the total partition count.
`DirectPort`	`UInt16`	A list of four ports to use for direct connectivity to the emulator's backend. The default list is `10251`, `10252`, `10253`, and `10254`.
`EnableMongoDb`	`SwitchParameter`	Specifies that API for MongoDB endpoint is enabled. The default is false.
`EnableCassandra`	`SwitchParameter`	Specifies that API for Apache Cassandra endpoint is enabled. The default is false.
`EnableGremlin`	`SwitchParameter`	Specifies that API for Apache Gremlin endpoint is enabled. The default is false.
`EnableTable`	`SwitchParameter`	Specifies that API for Table endpoint is enabled. The default is false.
`EnableSqlCompute`	`SwitchParameter`	Specifies that API for NoSQL endpoint is enabled. The default is false.
`EnablePreview`	`SwitchParameter`	Enables emulator features that are in preview and not fully matured to be on by default.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	By default the emulator regenerates its self-signed TLS/SSL certificate, if the certificate's SAN doesn't include the emulator host's domain name, local IP address ([v4]), `localhost`, and `127.0.0.1`. This option causes the emulator to fail at startup instead. You should then use the `New-CosmosDbEmulatorCertificate` option to create and install a new self-signed TLS/SSL certificate.
`GremlinPort`	`UInt16`	Port number to use for the API for Apache Gremlin. The default port number is `8901`.
`TablePort`	`UInt16`	Port number to use for the API for Table. The default port number is `8902`.
`SqlComputePort`	`UInt16`	Port number to use for the API for NoSQL. The default port number is `8903`.
`Key`	`String`	Authorization key for the emulator. This value must be the base 64 encoding of a 64-byte vector.
`MongoPort`	`UInt16`	Port number to use for the API for MongoDB. The default port number is `10250`.
`MongoApiVersion`	`String`	Specifies which version to use for the API for MongoDB. The default version is `4.0`.
`NoFirewall`	`SwitchParameter`	Specifies that no inbound port rules should be added to the emulator host's firewall.
`NoTelemetry`	`SwitchParameter`	Specifies that the cmdlet shouldn't collect data for the current emulator session.
`NoUI`	`SwitchParameter`	Specifies that the cmdlet shouldn't present the user interface or taskbar icon.
`NoWait`	`SwitchParameter`	Specifies that the cmdlet should return as soon as the emulator begins to start. By default the cmdlet waits until startup is complete and the emulator is ready to receive requests before returning.
`PartitionCount`	`UInt16`	The total number of partitions allocated by the emulator.
`Port`	`UInt16`	Port number for the emulator Gateway Service and Web UI. The default port number is `8081`.
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

Examples

Start the emulator and wait until it's ready to accept requests.
```
Start-CosmosDbEmulator
```
Start the emulator with 5 partitions reserved for each partitioned collection. The total number of partitions is set to the default: 25. Hence, the total number of partitioned collections that can be created is 5 = 25 partitions / 5 partitions/collection. Each partitioned collection is capped at 50 GB = 5 partitions * 10 GB / partiton.
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

Starts the emulator with alternative port numbers.

@parameters = {
    Port = 443 
    MongoPort = 27017 
    DirectPort = 20001,20002,20003,20004
}
Start-CosmosDbEmulator @parameters

`Stop-CosmosDbEmulator`

Stops the emulator. By default, this command waits until the emulator is fully shut down. Use the -NoWait option, if you wish the cmdlet to return as soon as the emulator begins to shut down.

Syntax

Stop-CosmosDbEmulator 
    [[-AlternativeInstallLocation] <String>]
    [-NoWait] [[-Timeout] <UInt32>] [-Trace] 
    [<CommonParameters>]

Parameters

Name	Type	Description
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	Specifies that the cmdlet should return as soon as the shutdown begins.
`Trace`	`SwitchParameter`

Examples

@parameters = {
    NoWait = $true
}
Stop-CosmosDbEmulator @parameters

`Uninstall-CosmosDbEmulator`

Uninstalls the emulator and optionally removes the full contents of $env:LOCALAPPDATA\CosmosDbEmulator. The cmdlet ensures the emulator is stopped before uninstalling it.

Syntax

Uninstall-CosmosDbEmulator 
    [-RemoveData] 
    [<CommonParameters>]

Parameters

Name	Type	Description
`RemoveData`	`SwitchParameter`	Specifies that the cmdlet should delete all data after it removes the emulator.

Examples

@parameters = {
    RemoveData = $false
}
Uninstall-CosmosDbEmulator @parameters

Change the number of default containers

By default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB software development kits (SDKs)), or 5 unlimited containers using the emulator. By modifying the PartitionCount value, you can create up to 250 fixed size containers or 50 unlimited containers, or any combination of the two that doesn't exceed 250 fixed size containers (where one unlimited container = 5 fixed size containers). However we don't recommend that you set up the emulator to run with more than 200 fixed size containers. Because of the overhead that it adds to the disk IO operations, which result in unpredictable timeouts when using the endpoint APIs.

If you attempt to create a container after the current partition count is exceeded, the emulator throws a ServiceUnavailable exception, with the following message.

Sorry, we are currently experiencing high demand in this region, and cannot fulfill your request at this time. We work continuously to bring more and more capacity online, and encourage you to try again.
ActivityId: 12345678-1234-1234-1234-123456789abc

To change the number of containers available in the emulator, run the following steps:

Delete all local emulator data by right-clicking the emulator icon on the system tray, and then clicking Reset Data….
Delete all emulator data in this folder %LOCALAPPDATA%\CosmosDBEmulator.
Exit all open instances by right-clicking the emulator icon on the system tray, and then clicking Exit. It might take a minute for all instances to exit.
Install the latest version of the emulator.
Launch the emulator with the PartitionCount flag by setting a value <= 250. For example: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Command-line and PowerShell reference for Windows (local) emulator

Manage the emulator with command-line syntax

Manage the emulator with PowerShell cmdlets

`Get-CosmosDbEmulatorStatus`

Syntax

Parameters

Examples

`Start-CosmosDbEmulator`

Syntax

Parameters

Examples

`Stop-CosmosDbEmulator`

Syntax

Parameters

Examples

`Uninstall-CosmosDbEmulator`

Syntax

Parameters

Examples

Change the number of default containers

Next steps

Additional resources