MongoDB Atlas CLI: Managing Databases From the Command Line

MongoDB Atlas is a cloud-based database service that lets you deploy, manage, and scale MongoDB databases. You can manage Atlas through the Atlas UI, a web-based interface, or the Atlas CLI, a command-line tool that lets you perform the same tasks using commands.

The MongoDB Atlas CLI offers a faster alternative to the Atlas UI. You can run and automate database management tasks directly from your terminal.

In this article, I'll walk you through using the Atlas CLI to manage your databases.

Prerequisites

Before you start, make sure you have:

• A MongoDB Atlas account.
• Basic command-line familiarity.
• Atlas CLI installation requirements for your operating system.

Structure of the CLI Commands

The MongoDB Atlas CLI follows a consistent command structure:

atlas [command] [subcommand] [flags]

When you run a command without any subcommands or flags, the CLI displays help information that includes:

• Usage: How to use the command.
• Aliases: Alternative names for the command.
• Available commands: Subcommands you can run.
• Flags: Options specific to the command.
• Global flags: Options available across all CLI commands.

For example, if you run:

atlas clusters

You will get a response similar to this:

Manage clusters for your project. The clusters command provides access to your cluster configurations. You can create, edit, and delete clusters.

Usage:
  atlas clusters [command]

Aliases:
  clusters, cluster

Available Commands:
  list              Return all clusters for your project.
  describe          Return the details for the specified cluster for your project.
  advancedSettings  Manage advanced configuration settings for your cluster.
 ...

Flags:
  -h, --help   help for clusters

Global Flags:
  -P, --profile string   Name of the profile to use from your configuration file. To learn about profiles for the Atlas CLI, see https://dochub.mongodb.org/core/atlas-cli-save-connection-settings.

Use "atlas clusters [command] --help" for more information about a command.

Command names, arguments, and flag names in the Atlas CLI are case-sensitive. Use the exact capitalization shown in the examples—for example, --orgId not --orgID.

Create a MongoDB Deployment

A deployment is a running instance of MongoDB that stores and serves your data. Each deployment includes the database servers, storage, networking, and automated backups. MongoDB Atlas handles the infrastructure management, so you can focus on using the database rather than maintaining servers.

To create a MongoDB deployment, install or update the Atlas CLI, then run the command:

atlas setup

The atlas setup command walks you through an interactive process. It prompts you for configuration choices and creates a project, provisions a cluster, and configures basic security settings.

Authenticate With an Existing Deployment

If you already have an existing MongoDB Atlas deployment and want to manage it with the CLI, you need to authenticate. To log in, run:

atlas auth login

This command prompts you to select your authentication type, then provides a one-time verification code. Copy the code and paste it into the browser when prompted. For example:

atlas auth login
? Select authentication type: UserAccount

To verify your account, copy your one-time verification code:
QPWF-6GT4

Paste the code in the browser when prompted to activate your Atlas CLI. Your code will expire after 3 minutes.

To continue, go to https://account.mongodb.com/account/connect

Press Enter to open the browser and complete authentication...
Successfully logged in as your-email@example.com.

After authentication, you'll select a default organization and output format. The CLI stores your session, but it expires periodically. When you see a "session expired" error, run atlas auth login again.

Manage Profiles for Multiple Environments

Profiles let you manage multiple MongoDB Atlas environments from the same CLI installation. Each profile stores connection settings for a different environment, such as development, staging, or production.

Using profiles, you can quickly switch between environments without re-authenticating or changing configuration files. This is useful when you maintain separate MongoDB Atlas projects or organizations for different stages of your development workflow.

A common practice is to create separate Atlas projects for each environment and use profiles to manage them—for example:

• Development profile: Points to your dev project with a small M0 cluster for testing.
• Staging profile: Points to your staging project that mirrors production configuration.
• Production profile: Points to your production project with production-grade clusters.

Create profiles for different environments

When you first run atlas auth login, the CLI creates a default profile. To create additional profiles for other environments, use the --profile flag:

atlas auth login --profile dev

This creates a profile named "dev" and walks you through the authentication process. Repeat this for each environment:

atlas auth login --profile staging
atlas auth login --profile production

Each profile stores its own authentication credentials, default project, and organization settings.

List available profiles

To view all configured profiles, run:

atlas config list

This shows you all profile names you've created.

View profile details

To see the configuration for a specific profile, run:

atlas config describe <profileName>

For example:

atlas config describe dev

This displays the profile's settings, including the default organization and project IDs.

Switch between profiles

To use a specific profile for a command, add the --profile flag:

atlas clusters list --profile production

This lists clusters using the production profile's credentials and settings.

You can also set a default profile so you don't need to specify it with every command:

atlas config set --profile staging

After setting a default, all commands use that profile unless you override it with the --profile flag.

Update profile settings

To modify a profile's configuration, run:

atlas config set <setting> <value> --profile <profileName>

For example, to set a default project for the dev profile:

atlas config set project_id 5f8e8d9a1b2c3d4e5f6g7h8i --profile dev

Rename profiles

To rename a profile, run:

atlas config rename <oldName> <newName>

For example:

atlas config rename dev development

Manage Projects

Projects in MongoDB Atlas organize your clusters, users, and settings. Think of a project as a container that groups related database resources together.

Each project contains multiple clusters and has its own set of users and access controls. This separation is useful when you have different applications, environments, or teams that need isolated database resources.

Create projects

To create a new project, run:

atlas projects create <projectName> [options]

Use a descriptive project name that indicates the project’s purpose, such as "ecommerce-transactions" or "mobile-app-staging."

[options] includes flags that modify how and where the project is created. For example, you can specify the organization to create the project in:

atlas projects create mobile-app-staging --orgId <organizationId>

The --orgId flag specifies the organization in which to create the project. It's required unless you have a default organization set. You can run the command atlas organizations list to get a list of your organizations and their Id. 

In all examples, replace placeholders like <projectId>, <clusterName>, and <username> with your actual project, cluster, or user names and identifiers.

Update projects

To update project settings, use:

atlas projects update <projectId> [options]

For example, you can use the --name flag as an option to change the project name:

atlas projects update <projectId> --name newProjectName

List projects

To list all projects in your organization, use:

atlas projects list [options]

The preceding command uses --orgId flag as an option to specify which organization to list projects from:

atlas projects list --orgId <organizationId>

You can also control the output format, such as displaying results in JSON:

atlas projects list --output json

Delete projects

You can delete a project using an Atlas CLI command.

atlas projects delete <projectId> --orgId <organizationId>

You can’t delete a project that still contains active clusters. So before deleting a project, make sure you delete all the clusters within it.

Manage Clusters

Clusters are groups of MongoDB servers that store your data. Atlas manages the infrastructure, replication, and backup for your clusters.

Create clusters

To create a new cluster, run:

atlas clusters create <clusterName> [options]

[options] includes flags that specify the cluster configuration. For example, you can include additional options to configure the cloud provider, region, and MongoDB pricing tier:

atlas clusters create myCluster --provider AWS --region US_EAST_1 --tier M0

In this command, the --provider flag specifies the cloud provider, such as AWS, GCP, or Azure. The --region flag specifies the region where the cluster will be deployed. The --tier flag specifies the cluster size.

If you haven't set a default project, include the --projectId flag:

atlas clusters create myCluster --projectId <projectId> --provider AWS --region US_EAST_1 --tier M0

Describe clusters

To view details about a specific cluster, run:

atlas clusters describe <clusterName> --projectId <projectId>

This command shows you the cluster's configuration, size, region, and connection strings.

List clusters

To list all clusters in your project, run:

atlas clusters list --projectId <projectId>

The --projectId flag is required unless you've set a default project using:

atlas config set project_id <projectId>

Pause clusters

You can temporarily pause a cluster without deleting it. This stops the cluster’s operations but preserves your data and configuration:

atlas clusters pause <clusterName> --projectId <projectId>

Delete clusters

To delete a cluster permanently, run:

atlas clusters delete <clusterName> --projectId <projectId>

After creating your cluster, you must configure network security before you can connect to it.

Manage IP Access List Configuration

An IP access list controls which IP addresses can connect to your MongoDB Atlas clusters. Each project can have up to 200 IP access list entries. You can add individual IP addresses, CIDR-notated ranges, or AWS security group IDs. A CIDR-notated range defines a block of IP addresses using a base IP and a prefix—for example, 192.168.0.0/24. An AWS security group ID allows access from all resources within the specified AWS security group.

To manage IP access lists, you must have Project Owner access to the project.

Add IP addresses to the access list

To add your current IP address to the access list, run:

atlas accessLists create --currentIp --projectId <projectId>

The --currentIp flag automatically adds the IP address of the machine running the command. This is useful when you need quick access from your development machine.

To add a specific IP address, run:

atlas accessLists create <ipAddress> --type ipAddress --projectId <projectId>

<ipAddress> is the IP address you want to allow. For example:

atlas accessLists create 192.0.2.15 --type ipAddress --comment "Office network" --projectId <projectId>

The --comment flag adds a description to help you identify the entry later.

To add a range of IP addresses using CIDR notation, run:

atlas accessLists create <cidrBlock> --type cidrBlock --projectId <projectId>

For example:

atlas accessLists create 73.231.201.0/24 --type cidrBlock --comment "Development servers" --projectId <projectId>

Create temporary access list entries

To add an IP address that automatically expires after a set time, use the --deleteAfter flag. You can set expiration dates up to seven days in the future:

atlas accessLists create <ipAddress> --type ipAddress --deleteAfter <isoDateTime> --projectId <projectId>

The --deleteAfter flag accepts an ISO-8601 formatted date. For example:

atlas accessLists create 192.0.2.20 --type ipAddress --deleteAfter 2025-12-31T23:59:59Z --comment "Temporary contractor access" --projectId <projectId>

MongoDB Atlas automatically removes the entry after the specified date and time.

List IP access list entries

To view all IP access list entries in your project, run:

atlas accessLists list --projectId <projectId>

To view details about a specific entry, run:

atlas accessLists describe <entry> --projectId <projectId>

<entry> is the IP address, CIDR block, or AWS security group ID you want to view.

Delete IP access list entries

To remove an IP address from the access list, run:

atlas accessLists delete <entry> --projectId <projectId>

Manage Users and Roles

A role grants privileges to perform sets of actions on specific resources. A user is an entity that is granted one or more roles that determine what they can access in the database.

To configure database users and roles, you must have Organization Owner, Project Owner, or Project Database Access Admin access in MongoDB Atlas.

Manage users

To create a database user, run:

atlas dbusers create [builtInRole] [options]

[builtInRole] is one or more built-in roles to assign to the user. [options] includes flags that specify the user's credentials and configuration. For example:

atlas dbusers create --username myUser --password myPassword --role readWriteAnyDatabase --projectId <projectId>

The --username flag specifies the username. The --password flag specifies the password. The --role flag specifies the role to assign. In this case, the username is myUser, while the password is myPassword. 

To list all database users in your project, run:

atlas dbusers list --projectId <projectId>

To view details about a specific database user, run:

atlas dbusers describe <username> --projectId <projectId>

You can also update the database user. For example, to update a user's password, run:

atlas dbusers update myUser --password newPassword --projectId <projectId>

To update a user's roles, run:

atlas dbusers update myUser --role readWriteAnyDatabase --role dbAdmin --projectId <projectId>

To delete a specific database user, run:

atlas dbusers delete <username> --projectId <projectId>

Manage roles

There are two categories of roles you can assign to a user:

• Built-in roles
• Custom roles

Built-in roles

Built-in roles are predefined roles that MongoDB Atlas provides. They include common permission sets for different database use cases, such as:

• read: Grants read-only access to a specific database.
• readWrite: Lets you read and modify data in a specific database.
• readAnyDatabase: Grants read-only access to all databases except the local and config databases.
• readWriteAnyDatabase: Grants read and write access to all databases.
• dbAdmin: provides Administrative privileges for a specific database, such as creating indexes or viewing statistics.
• dbAdminAnyDatabase: Grants administrative privileges on all databases.
• clusterAdmin: Lets you manage the entire cluster, including replication and sharding.
• userAdminAnyDatabase: Lets you create and modify user accounts and roles across all databases.

You cannot edit or delete built-in roles. You can only assign them to users. To assign built-in roles when creating users, specify the role with the --role flag:

atlas dbusers create --username app-reader --password myPassword --role readAnyDatabase --projectId <projectId>

To assign or change the role of an existing user, run:

atlas dbusers update app-reader --role readWriteAnyDatabase --projectId <projectId>

See [Built-In Roles and Privileges](https://www.mongodb.com/docs/atlas/mongodb-users-roles-and-privileges/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=atlas-cli-datacamp&utm_term=megan.grant) for more built-in roles you can assign to users.

Custom roles

MongoDB Atlas lets you create custom roles when the built-in roles don't meet your needs. A custom role defines a set of specific privilege actions that match your application or team’s requirements.

When creating a custom role, decide which collections users should access and what actions on resources they should be allowed to perform—for example, reading, inserting, updating, or deleting data.

In MongoDB privilege definitions, you must use the uppercase privilege action name in your CLI command, such as FIND, not find. See Privilege Actions for more defined privileged actions a user can perform on a resource.

You can manage custom roles with the Atlas CLI.

To create a custom role, run:

atlas customDbRoles create <roleName> [options]

<roleName> is the name of the custom role you want to create. [options] includes flags that specify the role's permissions—for example:

atlas customDbRoles create customAnalyticsRole --privilege FIND@myDatabase.users

In the preceding command:

• customAnalyticsRole is the name of the new custom role. You can choose any descriptive name that reflects the role’s purpose.
• The --privilege flag specifies what actions on resources the role can perform.
• The format is action@database.collection, where @ separates the action from the resource.
• FIND is a privilege action recognized by MongoDB.
• myDatabase.users is the resource that the privilege applies to—in this case, the users collection in the myDatabase database.

To view details about a custom role, run:

atlas customDbRoles list --projectId <projectId>

The preceding command shows you all custom roles and their permissions.

To update a custom role, run:

atlas customDbRoles update <roleName> [options]

[options] includes flags that specify what to update. For example, to add a new privilege to an existing role, run:

atlas customDbRoles update customAnalyticsRole --privilege FIND@myDatabase.analytics --privilege INSERT@myDatabase.logs --projectId <projectId>

The preceding command updates the existing customAnalyticsRole to grant additional privileges. FIND@myDatabase.analytics allows the role to read documents from the analytics collection, and INSERT@myDatabase.logs allows it to add documents to the logs collection in the myDatabase database.

The --projectId flag specifies which MongoDB Atlas project the role belongs to.

To delete a custom role, run:

atlas customDbRoles delete <roleName> --projectId <projectId>

The process of assigning a custom role to a user is similar to assigning a built-in role. Use the --role flag with the atlas dbusers create or atlas dbusers update commands:

atlas dbusers create --username analytics-user --password myPassword --role customAnalyticsRole --projectId <projectId>

After creating database users and assigning roles, you're ready to connect to your cluster.

Retrieve Connection Strings

A connection string contains the information your applications need to connect to your Atlas cluster. The string includes the cluster hostname, authentication database, and connection options.

Before you can use a connection string, make sure you've configured your IP access list and created at least one database user.

Get the connection string for a cluster

To retrieve the connection string for a cluster, run:

atlas clusters connectionStrings describe <clusterName> --projectId <projectId>

This command returns the SRV connection string for your cluster.

Connection string formats

MongoDB Atlas provides two types of connection strings:

Standard connection string (mongodb://): Lists all cluster nodes explicitly. Use this format when you need to specify individual server addresses.

SRV connection string (mongodb+srv://): Uses DNS to retrieve cluster information automatically. This is the recommended format because it automatically updates if your cluster configuration changes.

Use the connection string

Replace <username> and <password> in the connection string with your database user credentials:

mongodb+srv://<username>:<password>@cluster0.example.mongodb.net/

For example, if your username is appUser and password is securePass123:

mongodb+srv://appUser:securePass123@cluster0.example.mongodb.net/

You can then use this connection string with MongoDB Drivers, the MongoDB Shell, or other MongoDB tools to connect to your cluster.

Manage Backups

Backups are copies of your database data that you can use to restore your cluster if data is lost or corrupted. Atlas automatically creates backups on a regular schedule.

Automated continuous backups are only available for M10+ dedicated clusters. M0 free-tier clusters do not have backup capabilities. M2/M5 shared clusters have basic cloud backups, but not continuous backup. For more information, see [Snapshots for Flex Clusters](https://www.mongodb.com/docs/atlas/backup-restore-cluster/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=atlas-cli-datacamp&utm_term=megan.grant#snapshots-for-flex-clusters).

To manage backups, you must have Organization Owner or Project Owner access in Atlas.

Create on-demand backups

To create an immediate backup, run:

atlas backups snapshots create <clusterName> --desc "Backup description" --projectId <projectId>

In the preceding command, --desc is a required flag describing the snapshot.

List available backups

To list all backups for a cluster, run:

atlas backups snapshots list <clusterName> --projectId <projectId>

Describe backup configurations

To view backup settings for a cluster, run:

atlas backups schedule describe <clusterName> --projectId <projectId>

Restore from backups

To restore data from a backup, run:

atlas backups restores start <clusterName> --snapshotId <snapshotId> --targetClusterName <targetClusterName> --projectId <projectId>

The --snapshotId flag specifies which backup to restore. The --targetClusterName flag specifies the name of the cluster where the data will be restored—for example:

atlas backups restores start myCluster --snapshotId 5f8e8d9a1b2c3d4e5f6g7h8i --targetClusterName myCluster-restored --projectId <projectId>

Delete backups

To delete a backup, run:

atlas backups snapshots delete <snapshotId> --projectId <projectId>

Conclusion

In this article, I've walked you through the structure of CLI commands, creating deployments, managing projects and clusters, configuring users and roles, and managing backups. You can automate these operations by combining them into scripts, which makes it easier to manage multiple environments and integrate database management into your development workflow.