Quick Start¶

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¶

Before you begin, review and ensure that your environment is compatible for installing and using MongoDB CLI.

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:

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
The access list entry 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.

1

Create a profile for the project.¶

Run the following command to create a profile called default.

mongocli config

2

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]
************************************

3

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 and Up Arrow keys to highlight the desired organization, or
- Type 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 Organization ID.

4

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 and Up Arrow keys to highlight the desired project, or
Type 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 Project ID.

5

Optional: Customize the MongoDB CLI output using a Go template.¶

To learn more about customizing the MongoDB CLI output fields and format using a Go template, see Customize the MongoDB CLI Output Using a Go Template.

Configure an Atlas Cluster¶

Use the mongocli atlas quickstart command to create an M2 cluster in Atlas, add your IP addresses or CIDR blocks to the project IP access list, and create a MongoDB database user to access the database.

You can run this command in two ways:

Interactive mode - the command prompts you for the cluster settings
Non-interactive mode - you run the command with the cluster settings

Click the tab to see the command for your preferred mode.

The command prompts you for the following settings. Enter the corresponding value when prompted:

Cluster name: getStarted
Service provider: AWS
Provider region: US_EAST-1
MongoDB DB username: testUser
Password: <changeMe>
IP address to add to the Access List: <your-IP-address>
Download and install MongoDB Shell: N

mongocli atlas quickstart

Determine Your Cluster Status¶

Run the mongocli atlas cluster watch command to determine if the cluster is available for use. The following command uses the default profile to access the Atlas project:

mongocli atlas cluster watch getStarted

Retrieve Your Cluster¶

To retrieve your cluster settings and status, issue the mongocli atlas cluster describe command.

mongocli atlas cluster describe getStarted --output json

Your command output should look similar to the following:

{
  "autoScaling": {
    "diskGBEnabled": false,
    "compute": {
      "enabled": false,
      "scaleDownEnabled": false
    }
  },
  "backupEnabled": false,
  "biConnector": {
    "enabled": false,
    "readPreference": "secondary"
  },
  "clusterType": "REPLICASET",
  "diskSizeGB": 0.5,
  "encryptionAtRestProvider": "NONE",
  "id": "5e29cf4e7a3e5a3f46554bde",
  "groupId": "<project-ID>",
  "mongoDBVersion": "4.4.4",
  "mongoDBMajorVersion": "4.4",
  "mongoURI": "mongodb://getStarted-shard-00-00.example.mongodb.net:27017,getStarted-shard-00-01.example.mongodb.net:27017,getStarted-shard-00-02.example.mongodb.net:27017",
  "mongoURIUpdated": "2020-08-12T14:36:23Z",
  "mongoURIWithOptions": "mongodb://getStarted-shard-00-00.example.mongodb.net:27017,getStarted-shard-00-01.example.mongodb.mongodb.net:27017,getStarted-shard-00-02.example.mongodb.net:27017/?ssl=true\u0026authSource=admin\u0026replicaSet=atlas-abcde4-shard-0",
  "name": "getStarted",
  "numShards": 1,
  "paused": false,
  "pitEnabled": false,
  "providerBackupEnabled": false,
  "providerSettings": {
    "backingProviderName": "AWS",
    "instanceSizeName": "M0",
    "providerName": "TENANT",
    "regionName": "US_EAST_1",
    "autoScaling": {
      "compute": {}
    }
  },
  "replicationFactor": 3,
  "replicationSpecs": [
    {
      "id": "5f33fdc96b0fb076cc13ef20",
      "numShards": 1,
      "zoneName": "Zone 1",
      "regionsConfig": {
        "US_EAST_1": {
          "analyticsNodes": 0,
          "electableNodes": 3,
          "priority": 7,
          "readOnlyNodes": 0
        }
      }
    }
  ],
  "srvAddress": "mongodb+srv://getStarted.example.mongodb.net",
  "stateName": "IDLE",
  "connectionStrings": {
    "standard": "mongodb://getStarted-shard-00-00.example.mongodb.net:27017,getStarted-shard-00-01.example.mongodb.net:27017,getStarted-shard-00-02.example.mongodb.net:27017/?ssl=true\u0026authSource=admin\u0026replicaSet=atlas-abcde4-shard-0",
    "standardSrv": "mongodb+srv://getStarted.example.mongodb.net"
  }
}

Get Your Cluster Connection String Using a Go Template¶

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

To retrieve the connection string for the getStarted cluster, run the following mongocli atlas cluster describe command with the template. The following command uses the default profile for accessing Atlas.

mongocli atlas clusters describe getStarted -o go-template="Parse: {{.SrvAddress}}"

The previous command returns a string similar to the following:

Parse: mongodb+srv://getstarted.example.mongodb.net

Use the connection string with the mongo shell to connect to the getStarted cluster. This example uses the following to connect to the Atlas cluster:

The connection string returned by the previous command
The username and password created in this tutorial

mongo "mongodb+srv://getstarted.example.mongodb.net" --username User1 --password ChangeThisPasswordToSomethingSecure

Summary¶

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

Give Feedback

← Customize the MongoDB CLI Output Using a Go Template Reference →