Navigation

Alpha Release of MongoDB CLI

This is a pre-release early version of MongoDB CLI. Do not use MongoDB CLI to manage production environments.

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 whitelist and MongoDB user for your Atlas cluster
Retrieve details about the new cluster

The reference pages for the CLIs 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¶

There are two ways to install MongoDB CLI. You can:

Clone the MongoDB CLI git repository
Download the binary

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:

Note

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

Atlas
Cloud Manager
Ops Manager

Configure the MongoDB CLI

You can configure the MongoDB CLI access to MongoDB Atlas using the mongocli config and mongocli config set commands. The commands in the following steps create a custom profile named atlasProfile in the ~/.config/mongocli.toml file and sets your programmatic API access keys and project ID in the profile. You can use this profile with all the other commands in this tutorial.

1

Create a custom profile for the Atlas project.¶

Run the following command to create a profile.

mongocli config --profile atlasProfile

To learn more about the mongocli config command, see mongocli config or Configure the MongoDB CLI.

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

You can create a cluster on Atlas using the MongoDB CLI cluster create command.

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

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

Example

mongocli atlas cluster create getStarted --provider AWS --region US_EAST_1 --instanceSize M10 --diskSizeGB 2 --mdbVersion 4.2 --members 3 --profile atlasProfile

Whitelist Your IP Address

For each project, you can create a list of trusted IP addresses, referred to as a whitelist, and connect to the clusters in the project from a trusted IP address. Run the following command to add IP addresses to your whitelist.

Replace the IP address with your connection IP address.

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

Create a MongoDB User

You must create a MongoDB user for you Atlas cluster with the dbuser create. The MongoDB user can access the database hosted in Atlas. Run the following command to add a MongoDB user. The command creates a MongoDB user with the following attributes:

Username: myMongoDbUser
Password: myMongoDbUserPwd

Note

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

mongocli atlas dbuser create --username myMongoDbUser --password myMongoDbUserPwd --role atlasAdmin@admin --profile atlasProfile

Retrieve Your Cluster

You can check whether your cluster was successfully created by retrieving your cluster details using the MongoDB CLI. Run the following command to retrieve the cluster. The command uses:

The specified profile to determine the ID of the project that contains the cluster.
The programmatic API access keys in the profile for authentication.

mongocli atlas cluster describe getStarted --profile atlasProfile

Your command output should look similar to the following:

{
      "autoScaling": {
            "diskGBEnabled": false
      },
      "backupEnabled": false,
      "biConnector": {
            "enabled": false,
            "readPreference": "secondary"
      },
      "clusterType": "REPLICASET",
      "diskSizeGB": 2,
      "encryptionAtRestProvider": "NONE",
      "id": "5e29cf4e7a3e5a3f46554bde",
      "groupId": "<project-ID>",
      "mongoDBVersion": "4.2.3",
      "mongoDBMajorVersion": "4.2",
      "mongoURI": "mongodb://getstarted-shard-00-00-7hgjn.mongodb.net:27017,getstarted-shard-00-01-7hgjn.mongodb.net:27017,getstarted-shard-00-02-7hgjn.mongodb.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-7hgjn.mongodb.net",
      "stateName": "IDLE"
}

Summary

Congratulations! You have successfully created a cluster in Atlas to host your data. You can view your cluster by logging in to the Atlas UI. You can also connect to your cluster using the mongoURI. For example, run the following command to connect using the mongoURI. Replace mongoURI with the value of mongoURI in your cluster describe command output.

mongo <mongoURI>

Configure the MongoDB CLI

You can configure the MongoDB CLI access to Cloud Manager using the mongocli config and mongocli config set commands. The commands in the following steps create a custom profile named cmProfile in the ~/.config/mongocli.toml file and sets your programmatic API access keys and project ID in the profile. You can use this profile to run all the other commands in this tutorial.

1

Create a custom profile for the Cloud Manager project.¶

Run the following command to create a profile. When the command prompts you for the Public API Key and Private API Key, enter the programmatic API keys that you generated.

mongocli config --service cloud-manager --profile cmProfile

To learn more about the mongocli config command, see mongocli config or Configure the MongoDB CLI.

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

You can create a cluster on Cloud Manager using the MongoDB CLI.

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.

{
  "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.¶

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

Retrieve the Cluster

You can check whether your cluster was created by retrieving your cluster details using the MongoDB CLI. Run the following command to retrieve the cluster. The following command retrieves a detailed description of the cluster named getStarted. The command uses:

The specified profile to determine the ID of the project that contains the cluster.
The programmatic API access keys in the profile to interact with the Cloud Manager project.

mongocli cloud-manager cluster describe getStarted --profile cmProfile

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 in Cloud Manager to host your data. You can view your cluster by logging in to the Cloud Manager UI. You can also connect to your cluster using the mongoURI. For example, run the following command to connect using the mongoURI. Replace mongoURI with the value of mongoURI in your cluster describe command output.

mongo <mongoURI>

Configure the MongoDB CLI

You can configure the MongoDB CLI access to Ops Manager using the mongocli config and mongocli config set commands. The commands in the following steps create a custom profile named omProfile in the ~/.config/mongocli.toml file and sets your programmatic API access keys and project ID in the profile. You can use this profile to run all the other commands in this tutorial.

1

Create a custom profile for the Ops Manager project.¶

Run the following command to create a profile. When the command prompts you for the Public API Key and Private API Key, enter the programmatic API keys that you generated.

mongocli config --service ops-manager --profile omProfile

To learn more about the mongocli config command, see mongocli config or Configure the MongoDB CLI.

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

You can create a cluster on Ops Manager using the MongoDB CLI.

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.

{
  "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.¶

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

Retrieve the Cluster

The following command retrieves a detailed description of the cluster named getStarted. The command uses the profile named omProfile:

To determine the ID of the project that contains the cluster.
For the programmatic API access keys to access the Ops Manager project.

mongocli ops-manager cluster describe getStarted --profile omProfile

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 in Ops Manager to host your data. You can view your cluster by logging in to the Ops Manager UI. You can also connect to your cluster using the mongoURI. For example, run the following command to connect using the mongoURI. Replace mongoURI with the value of mongoURI in your cluster describe command output.

mongo <mongoURI>

← Environment Variables Reference →