Navigation

    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.

    This tutorial requires the following:

    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

    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:

    Info With Circle IconCreated with Sketch.Note

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

    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

    Run the following command to create a profile called default.

    mongocli config
    2

    When prompted, enter the Public API Key and Private API Key for your deployment.

    ? Public API Key: abcdef
    ? Private API Key: [? for help]
    ************************************
    3

    If you entered API keys, the command displays the name and ID of organizations that your API key can access.

    1. 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)
    2. Press Enter.

    If you didn't enter API keys, the command prompts you to enter your Default Project ID.

    4

    If you entered API keys, the command displays the name and ID of projects that your API key can access.

    1. 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)
    2. Press Enter.

    If you didn't enter API keys, the command prompts you to enter your Default Organization ID.

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

    Info With Circle IconCreated with Sketch.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
    mongocli atlas cluster create getStarted --provider AWS --region US_EAST_1 --tier M10 --diskSizeGB 10 --mdbVersion 4.2 --members 3

    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

    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

      Info With Circle IconCreated with Sketch.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

    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"
    }

    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.

    Give Feedback