Docs Menu
Docs Home
/
MongoDB Atlas
/
MongoDB Command Line Interface

Configure the MongoDB CLI

On this page

  • Prerequisites
  • Procedure
  • Next Steps

You can define the settings that the MongoDB CLI uses to interact with MongoDB services like Atlas, Cloud Manager, and Ops Manager by using the mongocli auth login or mongocli config command. The first time you run one of these commands, the MongoDB CLI creates a configuration file called config.toml to store your settings.

Prerequisites

To configure the MongoDB CLI:

  • Add your IP or CIDR block to the API access list for your MongoDB service.

  • Generate a Programmatic API Key if you don't already have one.

    Note

    Programmatic API Keys are role-based. Different roles have different privileges and capabilities, and some MongoDB CLI commands are available to some roles but not others. Be sure that the roles assigned to your Programmatic API Key are appropriate for the commands you intend to use.

    To learn more about generating a Programmatic API Key for your MongoDB service, see the following documentation:

    • Atlas API Access

    • Cloud Manager API Access

    • Ops Manager API Acess

  • Set up the HTTP_PROXY or HTTPS_PROXY environment variable if your MongoDB CLI installation is behind a firewall and you want to use a proxy URL. MongoDB CLI supports http, https, and socks5 schemes. In addition, specify cloud.mongodb.com/ as the main target URL in the proxy service's access list. You must specify the username and password also if your proxy configuration enables authentication.

    To learn more, see Proxy server.

Procedure

1

Authenticate to Atlas.

  1. Run the mongocli auth login command:

    mongocli auth login

    The command opens a browser window and returns a one-time activation code. This code expires after 10 minutes.

  2. If you aren't signed in already, sign into your Atlas account in the browser.

  3. Paste your activation code into the browser and click Confirm Authorization.

2

Create a profile.

In your terminal, press Enter to create a profile called default in the MongoDB CLI Configuration File.

3

Choose your default organization.

  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.

4

Choose your default project.

  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.

5

Choose your default output format.

  1. Press the Down Arrow and Up Arrow keys to highlight the desired default output format:

    ? Default Output Format:  [Use arrows to move, type to filter]
    > plaintext
      json
    Option
    Description
    plaintext
    Human-readable output that includes all fields that MongoDB CLI returns.
    json
    JSON output that includes all fields that MongoDB CLI returns.

  2. Press Enter.

6

Specify the path to the MongoDB Shell, mongosh, on your system.

MongoDB CLI uses the specified mongosh path so that you can access your deployments. The default value is /usr/local/bin/mongosh. Press Enter to accept the default or:

  1. Specify the path to mongosh on your system.

    ? Default MongoDB Shell Path: [? for help] (/usr/local/bin/mongosh)

  2. Press Enter.

7

Optional: Add API Keys to your profile.

After successful authentication, you remain logged into the MongoDB CLI for 12 hours. For an account that needs programmatic access for longer than 12 hours, configure API Keys for the profile with the mongocli config set command:

mongocli config set public_api_key abcdef
mongocli config set private_api_key a123bc45-ab1c-234d-5678-f91234a5bc6d

Note

Programmatic API Keys are role-based. Different roles have different privileges and capabilities, and some MongoDB CLI commands are available to some roles but not others. Be sure to assign roles to your Programmatic API Key that are appropriate for the commands you intend to use.

To learn more about generating an API Key for Atlas, see Programmatic API Key.

8

Verify your profile.

View the configuration file or run the mongocli config describe command to verify your profile.

Example

The following command returns the settings in the default profile:

mongocli config describe default

The preceding command returns the following settings. For security purposes, the command redacts API keys in the output.

SETTING           VALUE
mongosh_path      /usr/local/bin/mongosh
org_id            5f1f39ffc902201990f12345
private_api_key   redacted
project_id        7ehf04abc10defb66c7d1234c
public_api_key    redacted
service           cloud

Example

The following command returns the settings in the profile named myMongoDB:

mongocli config describe myMongoDB

The command returns following settings. For security purposes, the command redacts API keys in the output.

SETTING           VALUE
org_id            5f1f39ffc902201990f12345
private_api_key   redacted
project_id        7ehf04abc10defb66c7d1234c
public_api_key    redacted
service           cloud
1

Authenticate to MongoDB Cloud Manager.

  1. Run the mongocli auth login command:

    mongocli auth login --cm

    The command opens a browser window and returns a one-time activation code. This code expires after 10 minutes.

  2. If you aren't signed in already, sign into your MongoDB Cloud Manager account in the browser.

  3. Paste your activation code into the browser and click Confirm Authorization.

2

Create a profile.

In your terminal, press Enter to create a profile called default in the MongoDB CLI Configuration File.

3

Choose your default organization.

  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.

4

Choose your default project.

  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.

5

Choose your default output format.

  1. Press the Down Arrow and Up Arrow keys to highlight the desired default output format:

    ? Default Output Format:  [Use arrows to move, type to filter]
    > plaintext
      json
    Option
    Description
    plaintext
    Human-readable output that includes all fields that MongoDB CLI returns.
    json
    JSON output that includes all fields that MongoDB CLI returns.

  2. Press Enter.

6

Specify the path to the MongoDB Shell, mongosh, on your system.

MongoDB CLI uses the specified mongosh path so that you can access your deployments. The default value is /usr/local/bin/mongosh. Press Enter to accept the default or:

  1. Specify the path to mongosh on your system.

    ? Default MongoDB Shell Path: [? for help] (/usr/local/bin/mongosh)

  2. Press Enter.

7

Optional: Add API Keys to your profile.

After successful authentication, you remain logged into the MongoDB CLI for 12 hours. For an account that needs programmatic access for longer than 12 hours, configure API Keys for the profile with the mongocli config set command:

mongocli config set public_api_key abcdef
mongocli config set private_api_key a123bc45-ab1c-234d-5678-f91234a5bc6d

Note

Programmatic API Keys are role-based. Different roles have different privileges and capabilities, and some MongoDB CLI commands are available to some roles but not others. Be sure to assign roles to your Programmatic API Key that are appropriate for the commands you intend to use.

To learn more about generating an API Key for MongoDB Cloud Manager, see API keys.

8

Verify your profile.

View the configuration file or run the mongocli config describe command to verify your profile.

Example

The following command returns the settings in the default profile:

mongocli config describe default

The preceding command returns the following settings. For security purposes, the command redacts API keys in the output.

SETTING           VALUE
mongosh_path      /usr/local/bin/mongosh
org_id            5f1f39ffc902201990f12345
private_api_key   redacted
project_id        7ehf04abc10defb66c7d1234c
public_api_key    redacted
service           cloud-manager

Example

The following command returns the settings in the profile named myMongoDB:

mongocli config describe myMongoDB

The command returns following settings. For security purposes, the command redacts API keys in the output.

SETTING           VALUE
org_id            5f1f39ffc902201990f12345
private_api_key   redacted
project_id        7ehf04abc10defb66c7d1234c
public_api_key    redacted
service           cloud-manager
1

Complete the prerequisites.

Before you configure the MongoDB CLI:

  1. Add your IP or CIDR block to the API access list for Ops Manager.

  2. Generate a Programmatic API Key if you don't already have one.

Note

Programmatic API Keys are role-based. Different roles have different privileges and capabilities, and some MongoDB CLI commands are available to some roles but not others. Be sure to assign roles to your Programmatic API Key that are appropriate for the commands you intend to use.

To learn more about generating a Programmatic API Key for Ops Manager, see Ops Manager API Access.

2

Create a profile.

This command creates a profile called default in the MongoDB CLI Configuration File.

Run the mongocli config command:

mongocli config --service ops-manager

This command creates a profile with a custom name in the MongoDB CLI Configuration File. To use this profile in a command, you must specify the profile with the --profile flag.

Run the mongocli config command:

mongocli config --service ops-manager --profile <profile-name>
3

Enter the URL you use to access Ops Manager.

? URL to Access Ops Manager: http://mms.example.com:8080
4

Optional: Enter your API keys.

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

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

Choose your default organization.

If you entered API keys, the command displays the name and ID of the 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 Organization ID.

6

Choose your default project.

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.

    ? Default Project ID:  [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 Project ID.

7

Choose your default output format.

  1. Press the Down Arrow and Up Arrow keys to highlight the desired default output format:

    ? Default Output Format:  [Use arrows to move, type to filter]
    > plaintext
      json
    Option
    Description
    plaintext
    Human-readable output that includes all fields that MongoDB CLI returns.
    json
    JSON output that includes all fields that MongoDB CLI returns.

  2. Press Enter.

8

Specify the path to the MongoDB Shell, mongosh, on your system.

MongoDB CLI uses the specified mongosh path so that you can access your deployments. The default value is /usr/local/bin/mongosh. Press Enter to accept the default or:

  1. Specify the path to mongosh on your system.

    ? Default MongoDB Shell Path: [? for help] (/usr/local/bin/mongosh)

  2. Press Enter.

9

Verify your profile.

View the configuration file or run the mongocli config describe command to verify your profile.

Example

The following command returns the settings in the default profile:

mongocli config describe default

The preceding command returns the following settings. For security purposes, the command redacts API keys in the output.

SETTING           VALUE
mongosh_path      /usr/local/bin/mongosh
ops_manager_url = https://mms.example.com:8080/
org_id            5f1f39ffc902201990f12345
private_api_key   redacted
project_id        7ehf04abc10defb66c7d1234c
public_api_key    redacted
service           ops-manager

Example

The following command returns the settings in the profile named myMongoDB:

mongocli config describe myMongoDB

The command returns following settings. For security purposes, the command redacts API keys in the output.

SETTING           VALUE
ops_manager_url = https://mms.example.com:8080/
org_id            5f1f39ffc902201990f12345
private_api_key   redacted
project_id        7ehf04abc10defb66c7d1234c
public_api_key    redacted
service           ops-manager

Next Steps

Back

Install or Update the MongoDB CLI

Next

MongoDB CLI Configuration File