Quick Start
On this page
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
projectCreate 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:
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:
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:
Procedure
Note
The following sections are organized by MongoDB service. Select the tab for your MongoDB service to proceed.
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.
Optional: Enter your Programmatic API Key.
When prompted, enter the Public API Key
and Private API Key
for your Atlas deployment.
? Public API Key: abcdef ? Private API Key: [? for help] ************************************
Choose your default organization.
If you entered API keys, the command displays the name and ID of organizations that your API key can access.
Select your organization:
Press the
Down Arrow
andUp Arrow
keys to highlight the desired organization, orType the organization name to filter the available organizations.
? Choose a default organization: [Use arrows to move, type to filter] Org1 (5e39bf1212121e685774c81c) Press
Enter
.
If you didn't enter API keys, the command prompts you to enter your
Default Project ID
.
Choose your default project.
If you entered API keys, the command displays the name and ID of projects that your API key can access.
Select your project:
Press the
Down Arrow
andUp Arrow
keys to highlight the desired project, orType the project name to filter the available projects.
? Choose a default project: [Use arrows to move, type to filter] Project1 (5e5ebffd0c04a97009061234) Project2 (5cfacee6014b761b07f15678) Project3 (5e39bf4979358e6857741212) Project4 (5c815cc7014b768fb67e3434) Press
Enter
.
If you didn't enter API keys, the command prompts you to enter your
Default Organization ID
.
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
GBMongoDB version:
4.2
Replica set members:
3
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.
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
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.
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" }
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.
Optional: Enter your API keys.
When prompted, enter the Public API Key
and Private API Key
for your MongoDB Cloud Manager deployment.
? Public API Key: abcdef ? Private API Key: [? for help] ************************************
Choose your default organization.
If you entered API keys, the command displays the name and ID of organizations that your API key can access.
Select your organization:
Press the
Down Arrow
andUp Arrow
keys to highlight the desired organization, orType the organization name to filter the available organizations.
? Choose a default organization: [Use arrows to move, type to filter] Org1 (5e39bf1212121e685774c81c) Press
Enter
.
If you didn't enter API keys, the command prompts you to enter your
Default Project ID
.
Choose your default project.
If you entered API keys, the command displays the name and ID of projects that your API key can access.
Select your project:
Press the
Down Arrow
andUp Arrow
keys to highlight the desired project, orType the project name to filter the available projects.
? Choose a default project: [Use arrows to move, type to filter] Project1 (5e5ebffd0c04a97009061234) Project2 (5cfacee6014b761b07f15678) Project3 (5e39bf4979358e6857741212) Project4 (5c815cc7014b768fb67e3434) Press
Enter
.
If you didn't enter API keys, the command prompts you to enter your
Default Organization ID
.
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
, andhost3
. 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
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.
{ "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 } ] }
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.
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 } ] }
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.
Enter the URL you use to access Ops Manager.
? URL to Access Ops Manager: http://mms.example.com:8080
Optional: Enter your API keys.
When prompted, enter the Public API Key
and Private API Key
for your Ops Manager deployment.
? Public API Key: abcdef ? Private API Key: [? for help] ************************************
Choose your default organization.
If you entered API keys, the command displays the name and ID of organizations that your API key can access.
Select your organization:
Press the
Down Arrow
andUp Arrow
keys to highlight the desired organization, orType the organization name to filter the available organizations.
? Choose a default organization: [Use arrows to move, type to filter] Org1 (5e39bf1212121e685774c81c) Press
Enter
.
If you didn't enter API keys, the command prompts you to enter your
Default Project ID
.
Choose your default project.
If you entered API keys, the command displays the name and ID of projects that your API key can access.
Select your project:
Press the
Down Arrow
andUp Arrow
keys to highlight the desired project, orType the project name to filter the available projects.
? Choose a default project: [Use arrows to move, type to filter] Project1 (5e5ebffd0c04a97009061234) Project2 (5cfacee6014b761b07f15678) Project3 (5e39bf4979358e6857741212) Project4 (5c815cc7014b768fb67e3434) Press
Enter
.
If you didn't enter API keys, the command prompts you to enter your
Default Organization ID
.
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
, andhost3
. 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
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.
{ "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 } ] }
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.
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.
You can also use the mongo
shell connect to your cluster with
the srvAddress
and appropriate connection string
options.
Congratulations! You have successfully created a cluster to host your data. You can view your cluster by logging in to the UI.
Congratulations! You have successfully created a cluster to host your data. You can view your cluster by logging in to the UI.