Quick Start¶

On this page

Prerequisites

MongoDB CLI provides a command-line interface for managing your MongoDB Atlas, MongoDB Cloud Manager, and MongoDB Ops Manager projects and clusters. This tutorial demonstrates how to:

Download, install, and configure MongoDB CLI
Create clusters in your Atlas, Cloud Manager, or Ops Manager project
Create a whitelist and MongoDB user for your Atlas cluster
Retrieve details about the new cluster

The reference pages for the commands mentioned in this tutorial are available in the Reference section.

Prerequisites¶

This tutorial requires the following:

A MongoDB account
An Atlas, Cloud Manager, or Ops Manager organization and project

Download and Install MongoDB CLI¶

See Install the MongoDB CLI for information on downloading and installing MongoDB CLI. After installing MongoDB CLI, run the following command to verify installation:

copy

mongocli help

Generate Programmatic Access Keys¶

MongoDB CLI uses Programmatic Access Keys to access the Atlas, Cloud Manager, or Ops Manager projects. Your Programmatic API Key must have the project owner role and it must be whitelisted for your IP address or CIDR range. To learn more about generating the Programmatic API Key, see:

Note

The following sections are organized by MongoDB service. Select the tab for your MongoDB service to proceed.

Atlas
Cloud Manager
Ops Manager

Configure the MongoDB CLI

You can configure MongoDB CLI access to your MongoDB service using the mongocli config and mongocli config set commands.

The following procedure creates the default profile in the configuration file. You can use this profile with all the other commands in this tutorial.

1

Create a profile for the project.¶

Run the following command to create the default profile.

copy

mongocli config

2

Set your credentials in your profile.¶

When the command prompts you for the Public API Key and Private API Key, enter the programmatic API keys that you generated.

3

Set the ID of the project in your profile.¶

When the command prompts you, enter your project ID.

Note

You can retrieve the list of projects, including their IDs, using the mongocli iam project list command.

Create a Cluster

Use the mongocli atlas cluster create command to create a cluster in Atlas.

Note

This feature is not available for M0 (Free Tier) clusters. For more information, see Atlas M0 (Free Tier) Limitations.

The following command creates a sample paid-tier cluster with the following settings:

Cluster name: getStarted
Service provider: AWS
Provider region: US_EAST-1
Cluster tier: M10
Disk size: 2 GB
MongoDB version: 4.2
Replica set members: 3

copy

mongocli atlas cluster create getStarted --provider AWS --region US_EAST_1 --tier M10 --diskSizeGB 10 --mdbVersion 4.2 --members 3

Whitelist Your IP Address

Atlas only allows incoming connections to the cluster from entries in the project’s whitelist. You can add individual IP addresses or CIDR blocks to the project IP whitelist.

Atlas supports specifying private IP addresses with VPC peered connections. For more information, see Set up a Network Peering Connection.

Run the following command to add entries to your whitelist. Replace the IP address with your connection IP address.

copy

mongocli atlas whitelist create <your-IP-address> --type ipAddress

Create a MongoDB User

If the Atlas project does not yet have a MongoDB database user configured, you must create one in order to access the database. Run the mongocli atlas dbuser create command to add a MongoDB database user.

The command creates a MongoDB user with the following attributes:

Username: User1
Password: ChangeThisPasswordToSomethingSecure

Note

The tutorial uses the password ChangeThisPasswordToSomethingSecure. Replace this password with a strong password.
Role: Atlas admin

copy

mongocli atlas dbuser create --username User1 --password ChangeThisPasswordToSomethingSecure --role atlasAdmin@admin

Retrieve Your Cluster

To check your cluster’s deployment status, issue the mongocli atlas cluster describe command.

copy

mongocli atlas cluster describe getStarted

Your command output should look similar to the following:

{
      "autoScaling": {
            "diskGBEnabled": false
      },
      "backupEnabled": false,
      "biConnector": {
            "enabled": false,
            "readPreference": "secondary"
      },
      "clusterType": "REPLICASET",
      "diskSizeGB": 10,
      "encryptionAtRestProvider": "NONE",
      "id": "5e29cf4e7a3e5a3f46554bde",
      "groupId": "<project-ID>",
      "mongoDBVersion": "4.2.3",
      "mongoDBMajorVersion": "4.2",
      "mongoURI": "mongodb://getstarted.mongodb.example.net:27017,getstarted.mongodb.example.net:27017,getstarted.mongodb.example.net:27017",
      "name": "getStarted",
      "numShards": 1,
      "paused": false,
      "providerBackupEnabled": false,
      "providerSettings": {
            "backingProviderName": "AWS",
            "instanceSizeName": "M10",
            "providerName": "TENANT",
            "regionName": "US_EAST_1"
      },
      "replicationFactor": 3,
      "replicationSpec": {
             "US_EAST_1": {
                   "analyticsNodes": 0,
                   "electableNodes": 3,
                   "priority": 7,
                   "readOnlyNodes": 0
             }
      },
      "replicationSpecs": [
            {
                   "id": "5e29cf3cf10fab4e2677c9f9",
                   "numShards": 1,
                   "zoneName": "Zone 1",
                   "regionsConfig": {
                         "US_EAST_1": {
                               "analyticsNodes": 0,
                               "electableNodes": 3,
                               "priority": 7,
                               "readOnlyNodes": 0
                         }
                 }
            }
      ],
      "srvAddress": "mongodb+srv://getstarted.mongodb.example.net",
      "stateName": "IDLE"
}

Summary

Congratulations! You have successfully created a cluster to host your data. You can view your cluster by logging in to the UI.

You can also use the mongo shell connect to your cluster with the srvAddress and appropriate connection string options.

Configure the MongoDB CLI

You can configure MongoDB CLI access to your MongoDB service using the mongocli config and mongocli config set commands.

The following procedure creates the default profile in the configuration file. You can use this profile with all the other commands in this tutorial.

1

Create a profile for the project.¶

Run the following command to create the default profile.

copy

mongocli config --service cloud-manager

2

Set your credentials in your profile.¶

When the command prompts you for the Public API Key and Private API Key, enter the programmatic API keys that you generated.

3

Set the ID of the project in your profile.¶

When the command prompts you, enter your project ID.

Note

You can retrieve the list of projects, including their IDs, using the mongocli iam project list command.

Create a Cluster

Use the mongocli cloud-manager cluster create command to create a cluster in Cloud Manager.

The following command creates a sample cluster with the following settings:

Cluster name: getStarted
MongoDB server version: 4.2.2
Feature compatibility version: 4.2
Replica set members: 3
Member hostnames: host1, host2, host3

Note

This tutorial uses the hostnames host1, host2, and host3. Replace these hostnames with valid MongoDB server hostnames.
Data directories for each mongod instance: /data/cluster/rs1, /data/cluster/rs2, /data/cluster/rs3
Log file path for each mongod instance: /data/cluster/rs1/mongodb.log, /data/cluster/rs2/mongodb.log, /data/cluster/rs3/mongodb.log
Port for each mongod process: 29010, 29020, 29030
Voting priority for each member: 1
Number of votes for each member: 1

1

Copy and paste the following cluster-wide and replica set configuration properties in a file named `getStartedCluster.json`.¶

To learn more about the configuration file properties, see Cluster Configuration File.

copy

{
  "name": "getStarted",
  "version": "4.2.2",
  "featureCompatibilityVersion": "4.2",
  "processes": [
    {
      "hostname": "host1",
      "dbPath": "/data/cluster/rs1",
      "logPath": "/data/cluster/rs1/mongodb.log",
      "priority": 1,
      "votes": 1,
      "port": 29010
    },
    {
      "hostname": "host2",
      "dbPath": "/data/cluster/rs2",
      "logPath": "/data/cluster/rs2/mongodb.log",
      "priority": 1,
      "votes": 1,
      "port": 29020
    },
    {
      "hostname": "host3",
      "dbPath": "/data/cluster/rs3",
      "logPath": "/data/cluster/rs3/mongodb.log",
      "priority": 1,
      "votes": 1,
      "port": 29030
    }
  ]
}

2

Run the following command to create the cluster.¶

copy

mongocli cloud-manager cluster create --file getStartedCluster.json

Retrieve the Cluster

You can check whether your cluster was successfully created by retrieving the cluster details using the mongocli cloud-manager cluster describe command.

copy

mongocli cloud-manager cluster describe getStarted

Your command output should look similar to the following:

{
       "mongoURI": "mongodb://host1:29010,host2:29020,host3:29030",
       "name": "getStarted",
       "processes": [
             {
                    "buildIndexes": true,
                    "db_path": "/data/cluster/rs1",
                    "featureCompatibilityVersion": "4.2",
                    "hostname": "host1",
                    "log_path": "/data/cluster/rs1/mongodb.log",
                    "name": "getStartedCluster",
                    "port": 29010,
                    "priority": 1,
                    "process_type": "mongod",
                    "slave_delay": 0,
                    "version": "4.2.2",
                    "votes": 1,
                    "arbiter_only": false,
                    "disabled": false,
                    "hidden": false
             },
             {
                    "buildIndexes": true,
                    "db_path": "/data/cluster/rs2",
                    "featureCompatibilityVersion": "4.2",
                    "hostname": "host2",
                    "log_path": "/data/cluster/rs2/mongodb.log",
                    "name": "getStartedCluster",
                    "port": 29020,
                    "priority": 1,
                    "process_type": "mongod",
                    "slave_delay": 0,
                    "version": "4.2.2",
                    "votes": 1,
                    "arbiter_only": false,
                    "disabled": false,
                    "hidden": false
             },
             {
                    "buildIndexes": true,
                    "db_path": "/data/cluster/rs3",
                    "featureCompatibilityVersion": "4.2",
                    "hostname": "host3",
                    "log_path": "/data/cluster/rs3/mongodb.log",
                    "name": "getStartedCluster",
                    "port": 29030,
                    "priority": 1,
                    "process_type": "mongod",
                    "slave_delay": 0,
                    "version": "4.2.2",
                    "votes": 1,
                    "arbiter_only": false,
                    "disabled": false,
                    "hidden": false
             }
      ]
}

Summary

Congratulations! You have successfully created a cluster to host your data. You can view your cluster by logging in to the UI.

Configure the MongoDB CLI

You can configure MongoDB CLI access to your MongoDB service using the mongocli config and mongocli config set commands.

The following procedure creates the default profile in the configuration file. You can use this profile with all the other commands in this tutorial.

1

Create a profile for the project.¶

Run the following command to create the default profile.

copy

mongocli config --service ops-manager

2

Set your credentials in your profile.¶

When the command prompts you for the Public API Key and Private API Key, enter the programmatic API keys that you generated.

3

Set the ID of the project in your profile.¶

When the command prompts you, enter your project ID.

Note

You can retrieve the list of projects, including their IDs, using the mongocli iam project list command.

Create a Cluster

Use the mongocli ops-manager cluster create command to create a cluster in Ops Manager.

The following command creates a sample cluster with the following settings:

Cluster name: getStarted
MongoDB server version: 4.2.2
Feature compatibility version: 4.2
Replica set members: 3
Member hostnames: host1, host2, host3

Note

This tutorial uses the hostnames host1, host2, and host3. Replace these hostnames with valid MongoDB server hostnames.
Data directories for each mongod instance: /data/cluster/rs1, /data/cluster/rs2, /data/cluster/rs3
Log file path for each mongod instance: /data/cluster/rs1/mongodb.log, /data/cluster/rs2/mongodb.log, /data/cluster/rs3/mongodb.log
Port for each mongod process: 29010, 29020, 29030
Voting priority for each member: 1
Number of votes for each member: 1

1

Copy and paste the following cluster-wide and replica set configuration properties in a file named `getStartedCluster.json`.¶

To learn more about the configuration file properties, see Cluster Configuration File.

copy

{
  "name": "getStarted",
  "version": "4.2.2",
  "featureCompatibilityVersion": "4.2",
  "processes": [
    {
      "hostname": "host1",
      "dbPath": "/data/cluster/rs1",
      "logPath": "/data/cluster/rs1/mongodb.log",
      "priority": 1,
      "votes": 1,
      "port": 29010
    },
    {
      "hostname": "host2",
      "dbPath": "/data/cluster/rs2",
      "logPath": "/data/cluster/rs2/mongodb.log",
      "priority": 1,
      "votes": 1,
      "port": 29020
    },
    {
      "hostname": "host3",
      "dbPath": "/data/cluster/rs3",
      "logPath": "/data/cluster/rs3/mongodb.log",
      "priority": 1,
      "votes": 1,
      "port": 29030
    }
  ]
}

2

Run the following command to create the cluster.¶

copy

mongocli ops-manager cluster create --file getStartedCluster.json

Retrieve the Cluster

You can check whether your cluster was successfully created by retrieving the cluster details using the mongocli ops-manager cluster describe command.

copy

mongocli ops-manager cluster describe getStarted

Your command output should look similar to the following:

{
       "mongoURI": "mongodb://host1:29010,host2:29020,host3:29030",
       "name": "getStarted",
       "processes": [
             {
                    "buildIndexes": true,
                    "db_path": "/data/cluster/rs1",
                    "featureCompatibilityVersion": "4.2",
               "hostname": "host1",
                    "log_path": "/data/cluster/rs1/mongodb.log",
                    "name": "getStartedCluster",
                    "port": 29010,
                    "priority": 1,
                    "process_type": "mongod",
                    "slave_delay": 0,
                    "version": "4.2.2",
                    "votes": 1,
                    "arbiter_only": false,
                    "disabled": false,
                    "hidden": false
             },
             {
                    "buildIndexes": true,
                    "db_path": "/data/cluster/rs2",
                    "featureCompatibilityVersion": "4.2",
                    "hostname": "host2",
                    "log_path": "/data/cluster/rs2/mongodb.log",
                    "name": "getStartedCluster",
                    "port": 29020,
                    "priority": 1,
                    "process_type": "mongod",
                    "slave_delay": 0,
                    "version": "4.2.2",
                    "votes": 1,
                    "arbiter_only": false,
                    "disabled": false,
                    "hidden": false
             },
             {
                    "buildIndexes": true,
                    "db_path": "/data/cluster/rs3",
                    "featureCompatibilityVersion": "4.2",
                    "hostname": "host3",
                    "log_path": "/data/cluster/rs3/mongodb.log",
                    "name": "getStartedCluster",
                    "port": 29030,
                    "priority": 1,
                    "process_type": "mongod",
                    "slave_delay": 0,
                    "version": "4.2.2",
                    "votes": 1,
                    "arbiter_only": false,
                    "disabled": false,
                    "hidden": false
             }
       ]
}

Summary

Congratulations! You have successfully created a cluster to host your data. You can view your cluster by logging in to the UI.

← Enable Autocomplete for the MongoDB CLI Reference →

Quick Start¶

Prerequisites¶

Download and Install MongoDB CLI¶

Generate Programmatic Access Keys¶

Configure the MongoDB CLI

Create a profile for the project.¶

Set your credentials in your profile.¶

Set the ID of the project in your profile.¶

Create a Cluster

Whitelist Your IP Address

Create a MongoDB User

Retrieve Your Cluster

Summary

Configure the MongoDB CLI

Create a profile for the project.¶

Set your credentials in your profile.¶

Set the ID of the project in your profile.¶

Create a Cluster

Copy and paste the following cluster-wide and replica set configuration properties in a file named getStartedCluster.json.¶

Run the following command to create the cluster.¶

Retrieve the Cluster

Summary

Configure the MongoDB CLI

Create a profile for the project.¶

Set your credentials in your profile.¶

Set the ID of the project in your profile.¶

Create a Cluster

Copy and paste the following cluster-wide and replica set configuration properties in a file named getStartedCluster.json.¶

Run the following command to create the cluster.¶

Retrieve the Cluster

Summary

Copy and paste the following cluster-wide and replica set configuration properties in a file named `getStartedCluster.json`.¶

Copy and paste the following cluster-wide and replica set configuration properties in a file named `getStartedCluster.json`.¶