// Tutorial //

How To Use the MongoDB Shell

Published on July 29, 2021
Default avatar
By Mateusz Papiernik
Software Engineer, CTO @Makimo
How To Use the MongoDB Shell

The author selected the Open Internet/Free Speech Fund to receive a donation as part of the Write for DOnations program.


Database systems such as MongoDB are typically used with an external application that connects to the database server and performs operations, such as reading and processing the data or writing new entries. In cases like this, you are not interacting with the database server directly. To perform administrative tasks on the database or execute ad-hoc database queries yourself, though, direct access might be needed.

That’s where the MongoDB shell comes in. The MongoDB shell is an interactive console you can use to connect to the database server and execute commands on it, allowing you to perform administrative tasks and read, write, or manipulate data directly. The MongoDB shell enables you to connect to the database from a command line prompt and interactively work with it from a terminal window. It also allows you to run external scripts to perform repeated tasks with greater convenience.

In this tutorial, you’ll use the MongoDB shell to connect to a MongoDB database and query the database interactively. You will also use the built-in help system and autocompletion features included in the shell.


To follow this tutorial, you will need:

Note: The linked tutorials on how to configure your server, install, and then secure MongoDB installation refer to Ubuntu 20.04. This tutorial concentrates on MongoDB itself, not the underlying operating system. It will generally work with any MongoDB installation regardless of the operating system as long as authentication has been enabled.

Step 1 — Connecting to the MongoDB Server

To open up the MongoDB shell, run the mongo command from your server prompt. By default, the mongo command opens a shell connected to a locally-installed MongoDB instance running on port 27017.

Try running the mongo command with no additional parameters:

  1. mongo

This will print a welcome message with some information about the server the shell is connected to, as well as what version of MongoDB is installed. The following example indicates that the MongoDB server is running on (a loopback interface representing localhost) on MongoDB’s default port (27017) and running version 4.4.6.

MongoDB shell version v4.4.6 connecting to: mongodb:// Implicit session: session { "id" : UUID("b9a48dc7-e821-4b09-a753-429eedf072c5") } MongoDB server version: 4.4.6

Below this message, the MongoDB shell’s prompt — indicated by a greater-than sign — will appear:

Try listing all the databases available on the server. Type show dbs after the shell prompt and press ENTER:

  1. show dbs

Assuming you followed the prerequisite tutorial on How To Secure MongoDB, this command won’t return any output. The reason for this is that, even though the MongoDB server is running and the shell was able to connect to it, you didn’t provide any authentication information. Because of this, you have no access rights to work with any of the server databases and the show dbs command returns nothing.

Exit the shell by typing:

  1. exit

The Mongo shell will print a brief goodbye message and return you to the system shell:


Note: Instead of typing the exit command, an alternative way to close the shell is to press CTRL + C instead.

Now try reconnecting the MongoDB shell to the database server, but this time provide a username and password to properly authenticate into your MongoDB instance. To do so, you’ll need to provide additional command line parameters, as in the following example:

  1. mongo -u AdminSammy -p --authenticationDatabase admin

This command consists of several parts:

  • -u: this flag sets the username used to authenticate into the MongoDB server. This example specifies the administrative user created in the prerequisite MongoDB security tutorial, AdminSammy. For this tutorial, you can replace this with your own administrative user’s username if different.
  • -p: this flag tells the MongoDB shell to use a password when connecting to the database. You will be prompted to provide a password in the terminal window after you press ENTER.
  • --authenticationDatabase: this option specifies the authentication database of the user you’re logging in as. Typically, administrative accounts are managed in the admin database, but if your user’s authentication database is different, enter that database in place of admin.

Note: To connect to a MongoDB server running on a different machine than localhost, you can add the -h flag followed by your server’s IP address to the shell command.

Enter the password set during installation and you’ll once again get access to the shell.

Now try executing the show dbs command once again:

  1. show dbs

This time, the command will return a list of all available databases in the system:

admin 0.000GB config 0.000GB local 0.000GB

Because you’ve authenticated as a privileged user, the shell will allow you to run commands on any of these databases.

Now that you have successfully connected to the MongoDB server using a MongoDB shell, you can move on to learning how to execute commands in the shell.

Step 2 — Executing Commands

As with other command line interfaces, the MongoDB shell accepts commands and returns the desired results to standard output. As mentioned previously, in MongoDB shell, all commands are typed into the command prompt denoted with the greater-than sign (>). Pressing ENTER after the command immediately executes it and returns the command output to the screen.

Most commands in MongoDB database are executed on a database or on a collection in a selected database. The currently-selected database is represented by the db object accessible through the shell. You can check which database is currently selected by typing db into the shell:

  1. db

On a freshly-connected shell instance, the selected database is always called test:


You can safely use this database to experiment with MongoDB and the MongoDB shell. To switch to another database, you can run the use command followed by the new database name. Try switching to a database called fruits:

  1. use fruits

The shell will inform you that you’re now using the new database:

switched to db fruits

You can verify this by typing db again to find the name of the currently-selected database:

  1. db

This time, the output will reflect the new database:


Notice that you haven’t explicitly created the fruits database. MongoDB allows you to run commands on databases and collections that don’t yet exist; it only creates these structures when an object is first inserted into them. Even though you have successfully changed the current database to fruits, this database does not exist yet.

Try creating this database by inserting an object into it. The following example outlines how to insert an object into a collection within the database called apples. By adding this object, the operation will create both the fruits database and the apples collection.

Type the following line into the MongoDB shell and press ENTER. Notice the highlighted collection name (apples):

  1. db.apples.insert(

Pressing ENTER after an open parenthesis will start a multi-line command prompt, allowing you to enter longer commands in more than one line. The insert command won’t register as complete until you enter a closing parenthesis. Until you do, the prompt will change from the greater-than sign to an ellipsis (...).

You don’t need to break up MongoDB commands into multiple lines like this, but doing so can make long commands easier to read and understand.

On the next line, enter the object within a pair of curly brackets ({ and }). This example document has only one field and value pair:

  1. {name: 'Red Delicious'}

When you once again press ENTER, another line prompt will be shown, allowing you to add further command parameters, like other documents or any specifications allowed by MongoDB’s insert method. For this example, though, you can end your input and run the operation by entering a closing parenthesis and pressing ENTER:

  1. )

This time, the Mongo shell will register the ending of the insert command and execute the whole statement.

WriteResult({ "nInserted" : 1 })

You can learn more about creating objects in the next tutorial in this series, How To Perform CRUD operations.

After inserting this new object into the database, both the fruits database and apples collection will exist. Check the list of available databases with show dbs command:

  1. show dbs

Again, this returns a list of all the available databases, but this time the list includes the fruits database:

admin 0.000GB config 0.000GB fruits 0.000GB local 0.000GB

To retrieve a list of collections available in the currently-selected database, the show collections command comes in handy:

  1. show collections

Since the fruits database is selected, it will only return the newly-created apples collection:


With that, you’ve learned how to execute commands in the MongoDB shell. You also created a sample object, which in turn created a new database and a new collection that is now persisted on the server.

In the final step of this guide, you’ll learn how to invoke the MongoDB shell’s help features to better understand commands and execute them with greater ease.

Step 3 — Getting Interactive Help from the Shell

The MongoDB shell has a built-in help system that you can use to get information on database system’s available commands and the objects stored within it. This introductory help screen can be accessed with the help command directly in the shell prompt:

  1. help

The MongoDB shell will return a list of more detailed help entries you can use to learn about more specific parts of the shell, as well as with a few examples of most commonly used commands:

db.help() help on db methods db.mycoll.help() help on collection methods sh.help() sharding helpers rs.help() replica set helpers help admin administrative help help connect connecting to a db help help keys key shortcuts help misc misc things to know help mr mapreduce show dbs show database names show collections show collections in current database show users show users in current database show profile show most recent system.profile entries with time >= 1ms show logs show the accessible logger names show log [name] prints out the last segment of log in memory, 'global' is default use <db_name> set current database db.mycoll.find() list objects in collection mycoll db.mycoll.find( { a : 1 } ) list objects in mycoll where a == 1 it result of the last line evaluated; use to further iterate DBQuery.shellBatchSize = x set default number of items to display on shell exit quit the mongo shell

The first two entries, highlighted in this example output, illustrate how to execute a help command for the current database and a collection within the current database, respectively. The example collection name given is mycoll, but any valid collection name can be used.

The last highlighted line — db.mycoll.find() — is an example of one way to retrieve an object from a collection using the find command, which lists objects in a given collection. Because collections are some of the most commonly used structures in a Mongo database, this step will go over how to use Mongo’s find() and help() collection-level methods.

First, access the apples collection’s help screen to find the commands available for this collection:

  1. db.apples.help()

Note: While the initial help command was just help, when executing a help method on database and collection objects you must follow the command with a pair of parentheses so it reads as help() and not just help.

The output for this command will be lengthy list of available commands you can perform on the apples collection:

DBCollection help db.apples.find().help() - show DBCursor help db.apples.bulkWrite( operations, <optional params> ) - bulk execute write operations, optional parameters are: w, wtimeout, j db.apples.count( query = {}, <optional params> ) - count the number of documents that matches the query, optional parameters are: limit, skip, hint, maxTimeMS db.apples.countDocuments( query = {}, <optional params> ) - count the number of documents that matches the query, optional parameters are: limit, skip, hint, maxTimeMS . . . db.apples.find([query],[fields]) - query is an optional query filter. fields is optional set of fields to return. e.g. db.apples.find( {x:77} , {name:1, x:1} ) db.apples.find(...).count() db.apples.find(...).limit(n) db.apples.find(...).skip(n) db.apples.find(...).sort(...) . . .

In addition to the pure list of available commands you can execute on the db.apples collection (each of which are followed by short descriptions of what the given command does), this help screen also gives usage examples for frequently-used commands such as find().

This bundled help system serves as a useful reference of available commands. You can use it to check your syntax in case you don’t remember the exact spelling or the acceptable fields for a command.

Since you’ve already learned from the help screens that find() can be used to retrieve objects from a collection, you can now try retrieving the object you created in the apples collection in the previous step.

However, this example will highlight another of MongoDB’s interactive help aids known as command completion. The MongoDB shell follows the pattern found in other popular shells such as Bash or zsh in which pressing the keyboard’s TAB key will automatically complete whatever command you’re in the process of typing.

Start by typing the following, but do not press ENTER yet:

  1. db.a

Instead of typing the collection name in full, press the TAB key on the keyboard. The MongoDB shell will respond with the list of all the available possibilities that begin with a:

> db.a db.adminCommand( db.aggregate( db.apples db.auth(

This output lists three commands, indicated by an opening parenthesis, as well as the apples collection.

Type one more letter into the shell:

  1. db.ap

Press TAB once more. This time, there are no other possibilities starting with ap and the MongoDB shell will automatically complete the entry and type db.apples for you. Follow the same principle and complete the find() command using TAB completion. Type fi but do not press ENTER:

  1. db.apples.fi

Pressing TAB will automatically complete the command name to db.apples.find. At this point, pressing TAB again would cause the shell to list further possibilities, but you can manually add a closing parenthesis to execute the find command:

  1. db.apples.find()

The shell will show a list of all the objects found in the apples collection. There will be only one object, the one you inserted previously:

{ "_id" : ObjectId("60f31447f5643f739b0276e9"), "name" : "Red Delicious" }

This example used the object creation and retrieval commands to illustrate how to use the interactive shell. You can learn more about working with database objects in the next tutorial in this series, How To Perform CRUD operations.

With that, you’ve learned how to use the built-in help system and the Mongo shell’s autocomplete feature.


By reading this article, you will have familiarized yourself with the MongoDB shell. The shell makes it possible to insert new objects into the database, query the existing collections, and perform administrative tasks for managing the database, its data, and its users.

The MongoDB shell exposes direct access to most of Mongo’s features, such as database and collection objects and methods, making it the primary tool to interactive with a database server. However, the same set of functions and methods can be used when working with MongoDB programmatically, either through MongoDB shell scripting or through the drivers MongoDB has made available for many programming languages.

You can execute commands from other articles in this series in the MongoDB shell following the principles described in this tutorial. We encourage you to learn more about MongoDB Shell in the official MongoDB documentation.

If you’ve enjoyed this tutorial and our broader community, consider checking out our DigitalOcean products which can also help you achieve your development goals.

Learn more here

Tutorial Series: How To Manage Data with MongoDB

MongoDB is a document-oriented NoSQL database management system (DBMS). Unlike traditional relational DBMSs, which store data in tables consisting of rows and columns, MongoDB stores data in JSON-like structures referred to as documents.

This series provides an overview of MongoDB’s features and how you can use them to manage and interact with your data.

About the authors
Default avatar
Software Engineer, CTO @Makimo

Creating bespoke software ◦ CTO & co-founder at Makimo. I’m a software enginner & a geek. I like making impossible things possible. And I need tea.

Default avatar
Manager, Developer Education

Technical Writer @ DigitalOcean

Still looking for an answer?

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!