Run Atlas CLI Commands with the Atlas Administration API

On this page

Syntax

Examples

Atlas CLI support for running commands with the Atlas Administration API is in Preview. The feature and the corresponding documentation might change at any time during the Preview period. You can provide feedback on this feature through the MongoDB Feedback Engine for Atlas CLI.

This tutorial shows you how to run Atlas CLI commands with the Atlas Administration API. You can use every Atlas Administration API resource and endpoint from the Atlas CLI to create and manage Atlas deployments. Atlas CLI support for the Atlas Administration API provides the following benefits:

Full feature parity with the Atlas Administration API.
Quicker access to new Atlas Administration API resources and endpoints.
A unified, predictable command structure for automation.
Ability to pin a desired API version, ensuring your scripts remain reliable, even if you update the CLI.

Syntax

To use Atlas CLI with the Atlas Administration API, run the command in the following format:

atlas api <tag> <operationId> [options]|--file <fileName>.json --version <api-resource-version>

Arguments

Argument

Necessity

Description

<tag>

Required

The name of the tag used in the Atlas Administration API documentation URL for the API resource. The tag is hyphen-separated in the Atlas Administration API documentation URL. However, you must convert it to camelcase in the Atlas CLI command syntax.

For example, consider the following URL for an Atlas Administration API resource:

https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Example-Tag-Name/

For accessing the resource in the preceding URL, replace <tag> with exampleTagName in the command syntax:

atlas api exampleTagName <operationId>

For more examples, see Examples.

<operationId>

Required

The identifier of the operation in the Atlas Administration API documentation URL for the API endpoint. The value is in camelcase format.

For example, consider the following URL for an Atlas Administration API endpoint operation:

https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Example-Tag-Name/operation/exampleEndpointOperationId

For performing the operation supported by the endpoint in the preceding URL, replace <tag> with exampleTagName and use the ID of the operation, exampleEndpointOperationId, as shown the command.

atlas api exampleTagName exampleEndpointOperationId [options]

For more examples, see Examples.

Options

You can pass the API path, query, and request body parameters as options with the command. You can specify the options directly with the command or using a JSON file. The command also supports the following options:

Option	Necessity	Description
`--file`	Conditional	JSON file that contains the API path, query, and request body parameters for the operation. This is required only if there are required path, query, or request body parameters for the operation that you aren't specifying directly with the command.
`--version`	Optional	API resource version to use. We recommend using it to pin your scripts to specific API versions. If omitted, the command defaults to the latest version (or your profile's configured version). However, we recommend explicitly setting the version to ensure your scripts remain stable. This protects your scripts from breaking when new API versions are released with potentially incompatible changes.

Examples

The following Atlas CLI command with the Atlas Administration API demonstrates how to retrieve a compressed (.gz) log file that contains a range of log messages for the specified host for the specified project:

atlas api monitoringAndLogs getHostLogs --groupId 5e2211c17a3e5a48f5497de3 --hostName mycluster-shard-00-02.7hgjn.mongodb.net --logName mongodb --output gzip --version 2025-03-12

The following Atlas CLI command with the Atlas Administration API demonstrates how to create a cluster by using the --file option.

atlas api clusters createCluster --groupId 5e2211c17a3e5a48f5497de3 --file cluster-config.json --version 2025-03-12

To learn more about creating a configuration file for a cluster, see Cluster Configuration File.

The following Atlas CLI command with the Atlas Administration API demonstrates how to simulate regional cloud provider outages. This simulation lets you test your application's failover behavior and disaster recovery procedures in a controlled environment separate from production. The command uses a file named outage_simulation.json with the following settings:

{
   "outageFilters": [
      {
         "cloudProvider": "AWS",
         "regionName": "US_EAST_1",
         "type": "REGION"
      }
   ]
}

atlas api clusterOutageSimulation startOutageSimulation --groupId 5e2211c17a3e5a48f5497de3 --clusterName myCluster --file outage_simulation.json --version 2025-03-12

{"clusterName":"myCluster","groupId":"5e2211c17a3e5a48f5497de3","id":"6808ed9bed0b0b51caee336b","outageFilters":[{"cloudProvider":"AWS","regionName":"US_EAST_1","type":"REGION"}],"startRequestDate":"2025-04-23T13:39:39Z","state":"START_REQUESTED"}

Back

Run Commands with Docker

Reference