NAME

mongo - MongoDB Shell

DESCRIPTION

mongo is an interactive JavaScript shell interface to MongoDB, which provides a powerful interface for systems administrators as well as a way for developers to test queries and operations directly with the database. mongo also provides a fully functional JavaScript environment for use with a MongoDB. This document addresses the basic invocation of the mongo shell and an overview of its usage.

OPTIONS

Core Options

mongo
--shell
Enables the shell interface. If you invoke the mongo command and specify a JavaScript file as an argument, or use --eval to specify JavaScript on the command line, the --shell option provides the user with a shell prompt after the file finishes executing.
--nodb
Prevents the shell from connecting to any database instances. Later, to connect to a database within the shell, see mongo-shell-new-connections.
--norc
Prevents the shell from sourcing and evaluating ~/.mongorc.js on start up.
--quiet
Silences output from the shell during the connection process.
--port <port>
Specifies the port where the mongod or mongos instance is listening. If --port is not specified, mongo attempts to connect to port 27017.
--host <hostname>
Specifies the name of the host machine where the mongod or mongos is running. If this is not specified, mongo attempts to connect to a MongoDB process running on the localhost.
--eval <javascript>
Evaluates a JavaScript expression that is specified as an argument. mongo does not load its own environment when evaluating code. As a result many options of the shell environment are not available.
--username <username>, -u
Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.
--password <password>, -p
Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.
--help, -h
Returns information on mongo options and usage.
--version
Returns the mongo release number.
--verbose
Increases the verbosity of the output of the shell during the connection process.
--ipv6
Enables IPv6 support, which allows mongo to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes, including mongo, disable IPv6 support by default.
<db address>
Specifies the "database address" of the database to connect to. For example:

mongo admin

The above command will connect the mongo shell to the admin database on the local machine. You may specify a remote database instance, with the resolvable hostname or IP address. Separate the database name from the hostname using a / character. See the following examples:

mongo mongodb1.example.net
mongo mongodb1/admin
mongo 10.8.8.10/test
<file.js>
Specifies a JavaScript file to run and then exit. Generally this should be the last option specified.

Optional

To specify a JavaScript file to execute and allow mongo to prompt you for a password using --password, pass the filename as the first parameter with --username and --password as the last options, as in the following:

mongo file.js --username username --password

Use the --shell option to return to a shell after the file finishes running.

Authentication Options

--authenticationDatabase <dbname>
New in version 2.4.

Specifies the database that holds the user's credentials. If you do not specify an authentication database, mongo assumes that the database specified as the argument to the --db option holds the user's credentials.

--authenticationMechanism <name>
New in version 2.4.

Specifies the authentication mechanism. By default, the authentication mechanism is MONGODB-CR, which is the MongoDB challenge/response authentication mechanism. In MongoDB Enterprise, mongo also includes support for GSSAPI to handle Kerberos authentication. See http://docs.mongodb.org/manual/tutorial/control-access-to-mongodb-with-kerberos-authentication for more information about Kerberos authentication.

SSL Options

--ssl
New in version 2.6.

Enables connection to a mongod or mongos that has SSL support enabled.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

--sslPEMKeyFile <filename>
New in version 2.6.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has sslCAFile enabled without sslWeakCertificateValidation.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

--sslPEMKeyPassword <value>
New in version 2.6.

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use --sslPEMKeyPassword only if the certificate-key file is encrypted. In all cases, mongo will redact the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify --sslPEMKeyPassword, mongo will prompt for a passphrase. See ssl-certificate-password.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

--sslCAFile <filename>
New in version 2.6.

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

--sslCRLFile <filename>
New in version 2.6.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

--sslFIPSMode
New in version 2.6.

Directs mongo to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use --sslFIPSMode.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

--sslAllowInvalidCertificates
New in version 2.6.

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the sslAllowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

The default distribution of MongoDB does not contain support for SSL. For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure-ssl.

FILES

~/.dbshell
mongo maintains a history of commands in the .dbshell file.

NOTE: mongo does not recorded interaction related to authentication in the history file, including authenticate and db.addUser().

WARNING: Versions of Windows mongo.exe earlier than 2.2.0 will save the .dbshell file in the mongo.exe working directory.

~/.mongorc.js
mongo will read the .mongorc.js file from the home directory of the user invoking mongo. In the file, users can define variables, customize the mongo shell prompt, or update information that they would like updated every time they launch a shell. If you use the shell to evaluate a JavaScript file or expression either on the command line with --eval or by specifying a .js file to mongo, mongo will read the .mongorc.js file after the JavaScript has finished processing.

Specify the --norc option to disable reading .mongorc.js.

/etc/mongorc.js
Global mongorc.js file which the mongo shell evaluates upon start-up. If a user also has a .mongorc.js file located in the HOME directory, the mongo shell evaluates the global /etc/mongorc.js file before evaluating the user's .mongorc.js file.

/etc/mongorc.js must have read permission for the user running the shell. The --norc option for mongo suppresses only the user's .mongorc.js file.

On Windows, the global mongorc.js </etc/mongorc.js> exists in the %ProgramData%\MongoDB directory.

/tmp/mongo_edit<time_t>.js
Created by mongo when editing a file. If the file exists, mongo will append an integer from 1 to 10 to the time value to attempt to create a unique file.
%TEMP%mongo_edit<time_t>.js
Created by mongo.exe on Windows when editing a file. If the file exists, mongo will append an integer from 1 to 10 to the time value to attempt to create a unique file.

ENVIRONMENT

EDITOR
Specifies the path to an editor to use with the edit shell command. A JavaScript variable EDITOR will override the value of EDITOR.
HOME
Specifies the path to the home directory where mongo will read the .mongorc.js file and write the .dbshell file.
HOMEDRIVE
On Windows systems, HOMEDRIVE specifies the path the directory where mongo will read the .mongorc.js file and write the .dbshell file.
HOMEPATH
Specifies the Windows path to the home directory where mongo will read the .mongorc.js file and write the .dbshell file.

KEYBOARD SHORTCUTS

The mongo shell supports the following keyboard shortcuts: [1]


Keybinding Function

Up arrow Retrieve previous command from history

Down-arrow Retrieve next command from history

Home Go to beginning of the line

End Go to end of the line

Tab Autocomplete method/command

Left-arrow Go backward one character

Right-arrow Go forward one character

Ctrl-left-arrow Go backward one word

Ctrl-right-arrow Go forward one word

Meta-left-arrow Go backward one word

Meta-right-arrow Go forward one word

Ctrl-A Go to the beginning of the line

Ctrl-B Go backward one character

Ctrl-C Exit the mongo shell

Ctrl-D Delete a char (or exit the mongo shell)

Ctrl-E Go to the end of the line

Ctrl-F Go forward one character

Ctrl-G Abort

Ctrl-J Accept/evaluate the line

Ctrl-K Kill/erase the line

Ctrl-L or type cls Clear the screen

Ctrl-M Accept/evaluate the line

Ctrl-N Retrieve next command from history

Ctrl-P Retrieve previous command from history

Ctrl-R Reverse-search command history

Ctrl-S Forward-search command history

Ctrl-T Transpose characters

Ctrl-U Perform Unix line-discard

Ctrl-W Perform Unix word-rubout

Ctrl-Y Yank

Ctrl-Z Suspend (job control works in linux)

Ctrl-H Backward-delete a character

Ctrl-I Complete, same as Tab

Meta-B Go backward one word

Meta-C Capitalize word

Meta-D Kill word

Meta-F Go forward one word

Meta-L Change word to lowercase

Meta-U Change word to uppercase

Meta-Y Yank-pop

Meta-Backspace Backward-kill word

Meta-< Retrieve the first command in command history

Meta-> Retrieve the last command in command history

[1]
MongoDB accommodates multiple keybinding. Since 2.0, mongo includes support for basic emacs keybindings.

USE

Typically users invoke the shell with the mongo command at the system prompt. Consider the following examples for other scenarios.

To connect to a database on a remote host using authentication and a non-standard port, use the following form:

mongo --username <user> --password <pass> --host <host> --port 28015

Alternatively, consider the following short form:

mongo -u <user> -p <pass> --host <host> --port 28015

Replace <user>, <pass>, and <host> with the appropriate values for your situation and substitute or omit the --port as needed.

To execute a JavaScript file without evaluating the ~/.mongorc.js file before starting a shell session, use the following form:

mongo --shell --norc alternate-environment.js

To execute a JavaScript file with authentication, with password prompted rather than provided on the command-line, use the following form:

mongo script-file.js -u <user> -p

To print return a query as JSON, from the system prompt using the --eval option, use the following form:

mongo --eval 'db.collection.find().forEach(printjson)'

Use single quotes (e.g. ') to enclose the JavaScript, as well as the additional JavaScript required to generate this output.

AUTHOR

MongoDB Documentation Project

COPYRIGHT

2011-2014, MongoDB, Inc.