Docs Menu
Docs Home
/ /
Atlas CLI
/

Save Connection Settings

On this page

  • Locate the Configuration File
  • Create a Profile
  • Update a Profile
  • Run a Command with a Profile

You can save your frequently-used connection settings as profiles. Profiles store the project IDs, organization IDs, and, optionally, API keys to use in future Atlas CLI sessions. To save time, you can specify a profile instead of using the --projectId and --orgId flags with each command. The Atlas CLI stores your profiles in a configuration file called config.toml.

Note

Any settings stored in environment variables take precedence over settings stored in profiles. Any project or organization specified with the --projectId and --orgId flags take precedence over both the profile and the environment variables.

The Atlas CLI saves the configuration file to the following location depending on your operating system:

%AppData/atlascli
/Users/{username}/Library/Application Support/atlascli
$XDG_CONFIG_HOME/atlascli

By default, Atlas CLI saves the configuration file in the path defined in the $XDG_CONFIG_HOME environment variable. You can modify the path defined in the $XDG_CONFIG_HOME variable to your preferred location. To learn more about modifying the $XDG_CONFIG_HOME variable, see XDG Base Directory Specification.

If $XDG_CONFIG_HOME is not set, the Atlas CLI uses:

$HOME/.config/atlascli

The Atlas CLI grants the user who ran the command read and write access to the file.

The first time you run the atlas auth login or atlas config init command, the Atlas CLI automatically creates the config.toml file and a default profile. If you run a command without specifying a profile, environment variables, or --projectId and --orgId flags, the Atlas CLI uses the default profile for the command.

Select a connection method based on your use case:

Command
Authentication Method
Use Case
atlas auth login
Atlas login credentials and an authentication token
Best for non-programmatic use
atlas config init
API keys
Best for programmatic use

To learn more, see Select a Connection Method.

  • Install the Atlas CLI.

  • Add your host's IP address to the IP access list.

  • If you select atlas config init as your connection method, you must Configure API keys.

  • If your Atlas CLI installation is behind a firewall and you want to use a proxy URL, set up the HTTP_PROXY or HTTPS_PROXY environment variable.

    Important

    Atlas CLI supports http, https, and socks5 schemes. You must specify cloud.mongodb.com/ as the main target URL in the proxy service's access list. You must also specify the username and password if your proxy configuration enables authentication.

    To learn more, see Proxy server.

Select a use case and follow the procedure to create a profile.

Select the default profile or a named profile.

Create a default profile to:

  • Run a command without specifying a profile, environment variables, or --projectId and --orgId flags.

  • Use the --profile default flag.

Create a named profile to use the --profile <profileName> flag.

Follow these steps to create the default profile. If the default profile already exists, these commands update the default profile's values.

1

Run the atlas auth login command in your terminal.

atlas 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.

4

Return to the terminal. If you connect successfully, you see a message:

Successfully logged in as {Your Email Address}.

5

Press the Down Arrow and Up Arrow keys to highlight the desired organization and press Enter.

? Choose a default organization: [Use arrows to move, type to filter]
> Org1 (5e39bf1212121e685774c81c)

Note

If you have access to more than 500 organizations, you must type the organization ID or the organization name to filter the results before you use the arrows to select an organization.

6

Press the Down Arrow and Up Arrow keys to highlight the desired project and press Enter.

? Choose a default project: [Use arrows to move, type to filter]
Project1 (5e5ebffd0c04a97009061234)
Project2 (5cfacee6014b761b07f15678)
> Project3 (5e39bf4979358e6857741212)
Project4 (5c815cc7014b768fb67e3434)
7

Press the Down Arrow and Up Arrow keys to highlight the desired output format and press Enter.

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

The Atlas 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 specify the path to mongosh on your system and press Enter.

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

View the configuration file or run the atlas config describe command to verify your profile. For the default profile, the <profileName> is default.

atlas config describe <profileName>

The command returns following settings. The Atlas CLI redacts the access token and refresh token values for security.

SETTING VALUE
"access_token": "redacted",
"mongosh_path": "/usr/local/bin/mongosh",
"org_id": "60c9877baf349d6fc4fd9744",
"output": "json",
"project_id": "60c94857241ae99848af45ad",
"refresh_token": "redacted",
"service": "cloud"

Follow these steps to create a profile with a custom name.

1

Run the atlas auth login command in your terminal with the profile <profileName> flag. <profileName> should be the desired name for your new profile.

atlas auth login --profile myProfile

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.

4

Return to the terminal. If you connect successfully, you see a message:

Successfully logged in as {Your Email Address}.

5

Press the Down Arrow and Up Arrow keys to highlight the desired organization and press Enter.

? Choose a default organization: [Use arrows to move, type to filter]
> Org1 (5e39bf1212121e685774c81c)

Note

If you have access to more than 500 organizations, you must type the organization ID or the organization name to filter the results before you use the arrows to select an organization.

6

Press the Down Arrow and Up Arrow keys to highlight the desired project and press Enter.

? Choose a default project: [Use arrows to move, type to filter]
Project1 (5e5ebffd0c04a97009061234)
Project2 (5cfacee6014b761b07f15678)
> Project3 (5e39bf4979358e6857741212)
Project4 (5c815cc7014b768fb67e3434)
7

Press the Down Arrow and Up Arrow keys to highlight the desired output format and press Enter.

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

The Atlas 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 specify the path to mongosh on your system and press Enter.

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

View the configuration file or run the atlas config describe command to verify your profile. For the default profile, the <profileName> is default.

atlas config describe <profileName>

The command returns following settings. The Atlas CLI redacts the access token and refresh token values for security.

SETTING VALUE
"access_token": "redacted",
"mongosh_path": "/usr/local/bin/mongosh",
"org_id": "60c9877baf349d6fc4fd9744",
"output": "json",
"project_id": "60c94857241ae99848af45ad",
"refresh_token": "redacted",
"service": "cloud"

Select the default profile or a named profile.

Create a default profile to:

  • Run a command without specifying a profile, environment variables, or --projectId and --orgId flags.

  • Use the --profile default flag.

Create a named profile to use the --profile <profileName> flag.

Follow these steps to create the default profile. If the default profile already exists, these commands update the default profile's values.

1

Run the atlas config init command in your terminal.

atlas config init
2

Enter your public and private keys when prompted.

3

Press the Down Arrow and Up Arrow keys to highlight the desired organization and press Enter.

? Choose a default organization: [Use arrows to move, type to filter]
> Org1 (5e39bf1212121e685774c81c)
4

Press the Down Arrow and Up Arrow keys to highlight the desired project and press Enter.

? Choose a default project: [Use arrows to move, type to filter]
Project1 (5e5ebffd0c04a97009061234)
Project2 (5cfacee6014b761b07f15678)
> Project3 (5e39bf4979358e6857741212)
Project4 (5c815cc7014b768fb67e3434)
5

Press the Down Arrow and Up Arrow keys to highlight the desired output format and press Enter.

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

The Atlas 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 specify the path to mongosh on your system and press Enter.

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

View the configuration file or run the atlas config describe command to verify your profile. For the default profile, the <profileName> is default.

atlas config describe <profileName>

The command returns following settings. The Atlas CLI redacts the API key values for security.

SETTING VALUE
"mongosh_path": "/usr/local/bin/mongosh",
"org_id": "60c9877baf349d6fc4fd9744",
"output": "json",
"private_api_key": "redacted",
"project_id": "60c94857241ae99848af45ad",
"public_api_key": "redacted",
"service": "cloud"

Follow these steps to create a profile with a custom name.

1

Run the atlas config init command in your terminal with the profile <profileName> flag. <profileName> should be the desired name for your new profile.

atlas config init --profile myProfile
2

Enter your public and private keys when prompted.

3

Press the Down Arrow and Up Arrow keys to highlight the desired organization and press Enter.

? Choose a default organization: [Use arrows to move, type to filter]
> Org1 (5e39bf1212121e685774c81c)
4

Press the Down Arrow and Up Arrow keys to highlight the desired project and press Enter.

? Choose a default project: [Use arrows to move, type to filter]
Project1 (5e5ebffd0c04a97009061234)
Project2 (5cfacee6014b761b07f15678)
> Project3 (5e39bf4979358e6857741212)
Project4 (5c815cc7014b768fb67e3434)
5

Press the Down Arrow and Up Arrow keys to highlight the desired output format and press Enter.

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

The Atlas 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 specify the path to mongosh on your system and press Enter.

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

View the configuration file or run the atlas config describe command to verify your profile. For the default profile, the <profileName> is default.

atlas config describe <profileName>

The command returns following settings. The Atlas CLI redacts the API key values for security.

SETTING VALUE
"mongosh_path": "/usr/local/bin/mongosh",
"org_id": "60c9877baf349d6fc4fd9744",
"output": "json",
"private_api_key": "redacted",
"project_id": "60c94857241ae99848af45ad",
"public_api_key": "redacted",
"service": "cloud"

You can update the settings stored in your configuration file in the following ways:

  • Edit the config.toml file with a text editor.

  • Run the atlas config set command for a setting. This edits an individual value in the config.toml file.

To run an Atlas CLI command using a profile:

  • Create a Profile.

  • Append the --profile <profileName> flag to a command or omit the --profile <profileName> flag to use the default profile.

Example

This command uses a profile named myProfile:

atlas <command> --profile myProfile

This command uses the default profile:

atlas <command>

Back

Connect from the Atlas CLI