mongo(1)

LEGACY MONGO SHELL
The mongo shell has been deprecated in MongoDB v5.0. The replacement is mongosh.

Older mongo shell documentation is included with the corresponding documentation for that MongoDB release.

Quick Links to prior versions

    •   mongo shell v4.4 (https://docs.mongodb.com/v4.4/mongo/)

    •   mongo shell v4.2 (https://docs.mongodb.com/v4.2/mongo/)

    •   mongo shell v4.0 (https://docs.mongodb.com/v4.0/mongo/)

See Comparison of the mongo Shell and mongosh for more information.

DESCRIPTION

mongo is an interactive JavaScript shell interface to MongoDB, which provides a powerful interface for system 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.

The mongo shell is included as part of the MongoDB server installation. If you have already installed the server, the mongo shell is installed to the same location as the server binary.

Alternatively, if you would like to download the mongo shell separately from the MongoDB Server, you can install the shell as a standalone package by following these steps:

    •   Access the Download Center for your Edition of MongoDB:

        •   MongoDB Community Download Center (https://www.mongodb.com/try/download/community?tck=docs_server)

        •   MongoDB Enterprise Download Center (https://www.mongodb.com/try/download/enterprise?tck=docs_server)

    •   Select your preferred Version and Platform from the dropdowns.

    •   Select the Package to download according to your platform:

        •

            •   Platform

            •   Download Package

        •

            •   Windows

            •   Select the zip package to download an archive which includes the mongo shell.

        •

            •   macOS

            •   Select the tgz package to download an archive which includes the mongo shell.

        •

            •   Linux

            •   Select the tgz package to download the mongo shell.

    •   Copy the mongo shell from the archive to a location on your filesystem.

For additional installation guidance specific to your platform, or to install the mongo shell as part of a MongoDB Server installation, see the installation guide for your platform.

    •   Starting in MongoDB 4.2 (and 4.0.13), the mongo shell displays a warning message when connected to non-genuine MongoDB instances as these instances may behave differently from the official MongoDB instances; e.g. missing or incomplete features, different feature behaviors, etc.

    •   Starting in version 4.0, mongo disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.

SYNTAX

    •   You can run mongo shell without any command-line options use the default settings:

              mongo

    •   You can run mongo shell with a connection string that specifies the host and port and other connection options. For example, the following includes the tls:

              mongo "mongodb://mongodb0.example.com:27017/testdb?tls=true"

        The tls option is available starting in MongoDB 4.2. In earlier version, use the ssl option.

        To connect mongo shell to a replica set, you can specify in the connection string the replica set members and name:

              mongo "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA"

        For more information on the connection string options, see Connection String URI Format.

    •   You can run mongo shell with various command-line options. For example:

              mongo --host mongodb0.example.com:27017 [additional options]

              mongo --host mongodb0.example.com --port 27017 [additional options]

        For more information on the options available, see Options.

OPTIONS

    •   MongoDB deprecates the SSL options and instead adds new corresponding TLS 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.

mongo --nodb

    Prevents the shell from connecting to any database instances. Later, to connect to a database within the shell, see Opening New Connections.

mongo --norc

    Prevents the shell from sourcing and evaluating ~/.mongorc.js on start up.

mongo --quiet

    Silences output from the shell during the connection process.

mongo --port

    Specifies the port where the mongod or mongos instance is listening. If --port is not specified, mongo attempts to connect to port 27017.

mongo --host

    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.

    To connect to a replica set,

        Specify the replica set name and a seed list of set members. Use the following form:

              <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

    For TLS/SSL connections (--ssl),

        mongosh verifies that the hostname (specified in --host option or the connection string) matches the SAN (or, if SAN is not present, the CN) in the certificate presented by the mongod or mongos. If SAN is present, mongosh does not match against the CN. If the hostname does not match the SAN (or CN), mongosh will fail to connect.

        Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names.

    For DNS seedlist connections (https://docs.mongodb.com/manual/reference/connection-string/#dns-seedlist-connection-format/),

        Specify the connection protocol as mongodb+srv, followed by the DNS SRV hostname record and any options. The authSource and replicaSet options, if included in the connection string, will override any corresponding DNS-configured options set in the TXT record. Use of the mongodb+srv: connection string implicitly enables TLS/SSL (normally set with ssl=true) for the client connection. The TLS/SSL option can be turned off by setting ssl=false in the query string.

        Example:

              mongodb+srv://server.example.com/?connectionTimeout=3000ms

mongo --eval

    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.

mongo --username, mongo -u

    Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

    If connecting to a MongoDB Atlas (https://www.mongodb.com/cloud/atlas?tck=docs_server) cluster using the MONGODB-AWS authentication mechanism, specify your AWS access key ID in this field, or in the connection string. Alternatively, this value may also be supplied as the environment variable AWS_ACCESS_KEY_ID. See Connect to a MongoDB Atlas Cluster using AWS IAM Credentials.

mongo --password, mongo -p

    Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options. To force mongo to prompt for a password, enter the --password option as the last option and leave out the argument.

    If connecting to a MongoDB Atlas (https://www.mongodb.com/cloud/atlas?tck=docs_server) cluster using the MONGODB-AWS authentication mechanism, specify your AWS secret access key in this field, or in the connection string. Alternatively, this value may also be supplied as the environment variable AWS_SECRET_ACCESS_KEY. See Connect to a MongoDB Atlas Cluster using AWS IAM Credentials.

mongo --apiVersion

    Specifies the apiVersion. "1" is currently the only supported value.

mongo --apiStrict

    Specifies that the server will respond with APIStrictError if your application uses a command or behavior outside of the Versioned API.

    If you specify --apiStrict, you must also specify --apiVersion.

mongo --apiDeprecationErrors

    Specifies that the server will respond with APIDeprecationError if your application uses a command or behavior that is deprecated in the specified apiVersion.

    If you specify --apiDeprecationErrors, you must also specify --apiVersion.

mongo --awsIamSessionToken

    If connecting to a MongoDB Atlas (https://www.mongodb.com/cloud/atlas?tck=docs_server) cluster using the MONGODB-AWS authentication mechanism and using session tokens in addition to your AWS access key ID and secret access key, specify your AWS session token in this field, or in the connection string. Alternatively, this value may also be supplied as the environment variable AWS_SESSION_TOKEN. See Connect to a MongoDB Atlas Cluster using AWS IAM Credentials.

    Only valid when using the MONGODB-AWS authentication mechanism.

mongo --help, mongo -h

    Returns information on the options and use of mongo.

mongo --version

    Returns the mongo release number.

mongo --verbose

    Increases the verbosity of the output of the shell during the connection process.

mongo --networkMessageCompressors

    Enables network compression for communication between this mongo shell and:

        •   a mongod instance

        •   a mongos instance.

    You can specify the following compressors:

        •   snappy

        •   zlib (Available starting in MongoDB 3.6)

        •   zstd (Available starting in MongoDB 4.2)

    Messages are compressed when both parties enable network compression. Otherwise, messages between the parties are uncompressed.

    If you specify multiple compressors, then the order in which you list the compressors matter as well as the communication initiator. For example, if mongosh specifies the following network compressors zlib,snappy and the mongod specifies snappy,zlib, messages between mongosh and mongod uses zlib.

    If the parties do not share at least one common compressor, messages between the parties are uncompressed. For example, if mongosh specifies the network compressor zlib and mongod specifies snappy, messages between mongosh and mongod are not compressed.

mongo --ipv6

    Enables IPv6 support. mongo disables IPv6 by default.

    To connect to a MongoDB cluster via IPv6, you must specify both --ipv6 and --host <mongod/mongos IPv6 address> when starting the mongo shell.

    mongod and mongos disable IPv6 support by default. Specifying --ipv6 when connecting to a mongod/mongos does not enable IPv6 support on the mongod/mongos. For documentation on enabling IPv6 support on the mongod/mongos, see net.ipv6.

mongo <db

    Specifies the name of the database to connect to. For example:

          mongo admin

    The above command will connect the mongo shell to the admin database of the MongoDB deployment running 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/test
          mongo mongodb1/admin
          mongo 10.8.8.10/test

    This syntax is the only way to connect to a specific database.

    To specify alternate hosts and a database, you must use this syntax and cannot use --host or --port.

mongo --enableJavaScriptJIT

    Enable the JavaScript engine's JIT compiler.

mongo --disableJavaScriptJIT

    The JavaScript engine's JIT compiler is now disabled by default.

    Disables the JavaScript engine's JIT compiler.

mongo --disableJavaScriptProtection

    Allows fields of type javascript and javascriptWithScope (*Deprecated*) to be automatically marshalled to JavaScript functions in the mongo shell.

    With the --disableJavaScriptProtection flag set, it is possible to immediately execute JavaScript functions contained in documents. The following example demonstrates this behavior within the shell:

          > db.test.insert({ _id: 1, jsFunc: function(){ print("hello") } } )
          WriteResult({ "nInserted" : 1 })
          > var doc = db.test.findOne({ _id: 1 })
          > doc
          { "_id" : 1, "jsFunc" : function (){ print ("hello") } }
          > typeof doc.jsFunc
          function
          > doc.jsFunc()
          hello

    The default behavior (when mongo starts without the --disableJavaScriptProtection flag) is to convert embedded JavaScript functions to the non-executable MongoDB shell type Code. The following example demonstrates the default behavior within the shell:

          > db.test.insert({ _id: 1, jsFunc: function(){ print("hello") } } )
          WriteResult({ "nInserted" : 1 })
          > var doc = db.test.findOne({ _id: 1 })
          > doc
          { "_id" : 1, "jsFunc" : { "code" : "function (){print(
          > typeof doc.func
          object
          > doc.func instanceof Code
          true
          > doc.jsFunc()
          2016-11-09T12:30:36.808-08:00 E QUERY    [thread1] TypeError: doc.jsFunc is
          not a function :
          @(shell):1:1

mongo <file.js>

    Specifies a JavaScript file to run and then exit. Generally this should be the last option specified.

    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

mongo --authenticationDatabase

    Specifies the authentication database where the specified --username has been created. See Authentication Database.

    If you do not specify a value for --authenticationDatabase, mongo uses the database specified in the connection string.

    If using the GSSAPI (Kerberos), PLAIN (LDAP SASL), or MONGODB-AWS authentication mechanisms, you must set --authenticationDatabase to $external.

mongo --authenticationMechanism

    Default: SCRAM-SHA-1

    Specifies the authentication mechanism the mongo instance uses to authenticate to the mongod or mongos.

    With MongoDB 4.4, the mongo shell adds support for the new MONGODB-AWS authentication mechanism when connecting to a MongoDB Atlas (https://www.mongodb.com/cloud/atlas?tck=docs_server) cluster.

        •

            •   Value

            •   Description

        •

            •   SCRAM-SHA-1

            •   RFC 5802 (https://tools.ietf.org/html/rfc5802) standard Salted Challenge Response Authentication Mechanism using the SHA-1 hash function.

        •

            •   SCRAM-SHA-256

            •   RFC 7677 (https://tools.ietf.org/html/rfc7677) standard Salted Challenge Response Authentication Mechanism using the SHA-256 hash function.

                Requires featureCompatibilityVersion set to 4.0.

        •

            •   MONGODB-X509

            •   MongoDB TLS/SSL certificate authentication.

        •

            •   MONGODB-AWS

            •   External authentication using AWS IAM credentials for use in connecting to a MongoDB Atlas (https://www.mongodb.com/cloud/atlas?tck=docs_server) cluster. See Connect to a MongoDB Atlas Cluster using AWS IAM Credentials.

        •

            •   GSSAPI (Kerberos)

            •   External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server).

        •

            •   PLAIN (LDAP SASL)

            •   External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server).

mongo --gssapiHostName

    Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

    This option is available only in MongoDB Enterprise.

mongo --gssapiServiceName

    Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

    This option is available only in MongoDB Enterprise.

  TLS OPTIONS

Starting in version 4.0, mongo disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.

Configure mongod and mongos for TLS/SSL for full documentation of MongoDB's support.

mongo --tls

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

    Starting in version 3.2.6, if --tlsCAFile or net.tls.CAFile (or their aliases --sslCAFile or ssl.CAFile) is not specified, the system-wide CA certificate store will be used when connecting to an TLS/SSL-enabled server. In previous versions of MongoDB, mongosh exited with an error that it could not validate the certificate.

    To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --tlsCertificateKeyFile

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

    This option is required when using the --tls option to connect to a mongod or mongos instance that requires client certificates. That is, the mongo shell present this certificate to the server.

    mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --tlsCertificateKeyFilePassword

    Specifies the password to de-crypt the certificate-key file (i.e. --tlsCertificateKeyFile).

    Use the --tlsCertificateKeyFilePassword option only if the certificate-key file is encrypted. In all cases, the 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 the --tlsCertificateKeyFilePassword option, the mongo will prompt for a passphrase. See TLS/SSL Certificate Passphrase.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --tlsCAFile

    Specifies the .pem file that contains the root certificate chain from the Certificate Authority. This file is used to validate the certificate presented by the mongod/mongos instance.

    Specify the file name of the .pem file using relative or absolute paths.

    Starting in version 3.2.6, if --tlsCAFile or net.tls.CAFile (or their aliases --sslCAFile or ssl.CAFile) is not specified, the system-wide CA certificate store will be used when connecting to an TLS/SSL-enabled server. In previous versions of MongoDB, mongosh exited with an error that it could not validate the certificate.

    To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --tlsCRLFile

    In MongoDB 4.0 and earlier, see --sslCRLFile.

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

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

    Starting in version 4.4, to check for certificate revocation, MongoDB enables the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store.

mongo --tlsAllowInvalidHostnames

    Disables the validation of the hostnames in the certificate presented by the mongod/mongos instance. Allows mongo to connect to MongoDB instances even if the hostname in the server certificates do not match the server's host.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --tlsAllowInvalidCertificates

    Bypasses the validation checks for the certificates presented by the mongod/mongos instance and allows connections to servers that present invalid certificates.

    Starting in MongoDB 4.2, if you specify --tlsAllowInvalidateCertificates or net.tls.allowInvalidCertificates: true when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS connection but it is insufficient for authentication.

    Although available, avoid using the --sslAllowInvalidCertificates option if possible. If the use of --sslAllowInvalidCertificates is necessary, only use the option on systems where intrusion is not possible.

    If mongosh (and other MongoDB Tools) runs with the --sslAllowInvalidCertificates option, mongosh (and other MongoDB Tools) will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see --sslAllowInvalidHostnames.

    When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --tlsFIPSMode

    Directs the mongo to use the FIPS mode of the TLS/SSL library. Your system must have a FIPS compliant library to use the --tlsFIPSMode option.

    FIPS-compatible TLS/SSL is available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server). See Configure MongoDB for FIPS for more information.

mongo --tlsCertificateSelector

    Available on Windows and macOS as an alternative to --tlsCertificateKeyFile.

    The --tlsCertificateKeyFile and --tlsCertificateSelector options are mutually exclusive. You can only specify one.

    Specifies a certificate property in order to select a matching certificate from the operating system's certificate store.

    --tlsCertificateSelector accepts an argument of the format <property>=<value> where the property can be one of the following:

        •

            •   Property

            •   Value type

            •   Description

        •

            •   subject

            •   ASCII string

            •   Subject name or common name on certificate

        •

            •   thumbprint

            •   hex string

            •   A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA-1 digest.

                The thumbprint is sometimes referred to as a fingerprint.

    When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.

    mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.

mongo --tlsDisabledProtocols

    Disables the specified TLS protocols. The option recognizes the following protocols: TLS1_0, TLS1_1, TLS1_2, and starting in version 4.0.4 (and 3.6.9 and 3.4.24), TLS1_3.

        •   On macOS, you cannot disable TLS1_1 and leave both TLS1_0 and TLS1_2 enabled. You must also disable at least one of the other two; for example, TLS1_0,TLS1_1.

        •   To list multiple protocols, specify as a comma separated list of protocols. For example TLS1_0,TLS1_1.

        •   The specified disabled protocols overrides any default disabled protocols.

    Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS 1.1+ is available on the system. To enable the disabled TLS 1.0, specify none to --tlsDisabledProtocols. See Disable TLS 1.0.

  SSL OPTIONS (DEPRECATED)

Starting in version 4.2, the SSL options are deprecated. Use the TLS counterparts instead. The SSL protocol is deprecated and MongoDB supports TLS 1.0 and later.

Starting in version 4.0, mongo disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.

mongo --ssl

    Use --tls instead.

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

    Starting in version 3.2.6, if --tlsCAFile or net.tls.CAFile (or their aliases --sslCAFile or ssl.CAFile) is not specified, the system-wide CA certificate store will be used when connecting to an TLS/SSL-enabled server. In previous versions of MongoDB, mongosh exited with an error that it could not validate the certificate.

    To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslPEMKeyFile

    Use --tlsCertificateKeyFile instead.

    Specifies the .pem file that contains both the TLS/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 CAFile enabled without allowConnectionsWithoutCertificates.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslPEMKeyPassword

    Use --tlsCertificateKeyFilePassword instead.

    Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the 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 the --sslPEMKeyPassword option, the mongo will prompt for a passphrase. See TLS/SSL Certificate Passphrase.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslCAFile

    Use --tlsCAFile instead.

    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.

    Starting in version 3.2.6, if --tlsCAFile or net.tls.CAFile (or their aliases --sslCAFile or ssl.CAFile) is not specified, the system-wide CA certificate store will be used when connecting to an TLS/SSL-enabled server. In previous versions of MongoDB, mongosh exited with an error that it could not validate the certificate.

    To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslCertificateSelector

    Use --tlsCertificateSelector instead.

    Available on Windows and macOS as an alternative to --tlsCertificateKeyFile.

    --tlsCertificateKeyFile and --sslCertificateSelector options are mutually exclusive. You can only specify one.

    Specifies a certificate property in order to select a matching certificate from the operating system's certificate store.

    --sslCertificateSelector accepts an argument of the format <property>=<value> where the property can be one of the following:

        •

            •   Property

            •   Value type

            •   Description

        •

            •   subject

            •   ASCII string

            •   Subject name or common name on certificate

        •

            •   thumbprint

            •   hex string

            •   A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA-1 digest.

                The thumbprint is sometimes referred to as a fingerprint.

    When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.

mongo --sslCRLFile

    Use --tlsCRLFile instead.

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

    Starting in version 4.4, to check for certificate revocation, MongoDB enables the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslFIPSMode

    Use --tlsFIPSMode instead.

    Directs the mongo to use the FIPS mode of the TLS/SSL library. Your system must have a FIPS compliant library to use the --sslFIPSMode option.

    FIPS-compatible TLS/SSL is available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server). See Configure MongoDB for FIPS for more information.

mongo --sslAllowInvalidCertificates

    Use --tlsAllowInvalidCertificates instead.

    Bypasses the validation checks for server certificates and allows the use of invalid certificates to connect.

    Starting in MongoDB 4.2, if you specify --tlsAllowInvalidateCertificates or net.tls.allowInvalidCertificates: true when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS connection but it is insufficient for authentication.

    Although available, avoid using the --sslAllowInvalidCertificates option if possible. If the use of --sslAllowInvalidCertificates is necessary, only use the option on systems where intrusion is not possible.

    If mongosh (and other MongoDB Tools) runs with the --sslAllowInvalidCertificates option, mongosh (and other MongoDB Tools) will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see --sslAllowInvalidHostnames.

    When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslAllowInvalidHostnames

    Use --tlsAllowInvalidHostnames instead.

    Disables the validation of the hostnames in TLS/SSL certificates. Allows mongo to connect to MongoDB instances even if the hostname in their certificates do not match the specified hostname.

    For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

mongo --sslDisabledProtocols

    Use --tlsDisabledProtocols instead.

    Disables the specified TLS protocols. The option recognizes the following protocols: TLS1_0, TLS1_1, TLS1_2, and starting in version 4.0.4 (and 3.6.9), TLS1_3.

        •   On macOS, you cannot disable TLS1_1 and leave both TLS1_0 and TLS1_2 enabled. You must also disable at least one of the other two; for example, TLS1_0,TLS1_1.

        •   To list multiple protocols, specify as a comma separated list of protocols. For example TLS1_0,TLS1_1.

        •   The specified disabled protocols overrides any default disabled protocols.

    Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS 1.1+ is available on the system. To enable the disabled TLS 1.0, specify none to --sslDisabledProtocols. See Disable TLS 1.0.

  SESSIONS

mongo --retryWrites

    Enables retryable writes as the default for sessions in the mongo shell.

    For more information on sessions, see Client Sessions and Causal Consistency Guarantees.

  CLIENT-SIDE FIELD LEVEL ENCRYPTION OPTIONS

mongo --awsAccessKeyId

    An AWS Access Key (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) associated to an IAM user with List and Read permissions for the AWS Key Management Service (KMS). The mongo shell uses the specified --awsAccessKeyId to access the KMS.

    --awsAccessKeyId is required for enabling Client-Side Field Level Encryption for the mongo shell session. --awsAccessKeyId requires all of the following command line options:

        •   --awsSecretAccessKey

        •   --keyVaultNamespace

    If --awsAccessKeyId is omitted, use the Mongo() constructor within the shell session to enable client-side field level encryption.

    To mitigate the risk of leaking access keys into logs, consider specifying an environmental variable to --awsAccessKeyId.

mongo --awsSecretAccessKey

    An AWS Secret Key (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) associated to the specified --awsAccessKeyId.

    --awsSecretAccessKey is required for enabling Client-Side Field Level Encryption for the mongo shell session. --awsSecretAccessKey requires all of the following command line options:

        •   --awsAccessKeyId

        •   --keyVaultNamespace

    If --awsSecretAccessKey and its supporting options are omitted, use Mongo() within the shell session to enable client-side field level encryption.

    To mitigate the risk of leaking access keys into logs, consider specifying an environmental variable to --awsSecretAccessKey.

mongo --awsSessionToken

    An AWS Session Token (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) associated to the specified --awsAccessKeyId.

    --awsSessionToken is required for enabling Client-Side Field Level Encryption for the mongo shell session. --awsSessionToken requires all of the following command line options:

        •   --awsAccessKeyId

        •   --awsSecretAccessKey

        •   --keyVaultNamespace

    If --awsSessionToken and its supporting options are omitted, use Mongo() within the shell session to enable client-side field level encryption.

    To mitigate the risk of leaking access keys into logs, consider specifying an environmental variable to --awsSessionToken.

mongo --keyVaultNamespace

    The full namespace (<database>.<collection>) of the collection used as a key vault for Client-Side Field Level Encryption. --keyVaultNamespace is required for enabling client-side field level encryption. for the mongo shell session. mongo creates the specified namespace if it does not exist.

    --keyVaultNamespace requires all of the following command line options:

        •   --awsAccessKeyId

        •   --awsSecretAccessKey

    If --keyVaultNamespace and its supporting options are omitted, use the Mongo() constructor within the shell session to enable client-side field level encryption.

FILES

~/.dbshell

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

    mongo does not record interaction related to authentication in the history file, including authenticate and db.createUser().

~/.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 mongo --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%ngoDB 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:

    •

        •   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

USE

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

  CONNECT TO A MONGOD INSTANCE WITH ACCESS CONTROL

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

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

Alternatively, consider the following short form:

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

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

If you do not specify the password to the --password or -p command-line option, the mongo shell prompts for the password.

  CONNECT TO A REPLICA SET USING THE DNS SEEDLIST CONNECTION FORMAT

To connect to a replica set described using the DNS Seed List Connection Format, use the --host option to specify the connection string to the mongo shell. In the following example, the DNS configuration resembles:

      Record                            TTL   Class    Priority Weight Port  Target
      _mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27317 mongodb1.example.com.
      _mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27017 mongodb2.example.com.

The TXT record for the DNS entry includes the replicaSet and authSource options:

      Record              TTL   Class    Text
      server.example.com. 86400 IN TXT   "replicaSet=rs0&authSource=admin"

The following command then connects the mongo shell to the replica set:

      mongo --host "mongodb+srv://server.example.com/?username=allison"

The mongo shell will automatically prompt you to provide the password for the user specified in the username option.

  CONNECT TO A MONGODB ATLAS CLUSTER USING AWS IAM CREDENTIALS

To connect to a MongoDB Atlas (https://www.mongodb.com/cloud/atlas?tck=docs_server) cluster which has been configured to support authentication via AWS IAM credentials (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), provide a connection string to the mongo shell similar to the following:

      mongo 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS'

Connecting to Atlas using AWS IAM credentials in this manner uses the MONGODB-AWS authentication mechanism and the $external authSource, as shown in this example.

If using an AWS session token (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) as well, provide it with the AWS_SESSION_TOKEN authMechanismProperties value in your connection string, as follows:

      mongo 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<aws session token>'

If the AWS access key ID, secret access key, or session token include the following characters:

      : / ? # [ ] @

those characters must be converted using percent encoding (https://tools.ietf.org/html/rfc3986#section-2.1).

Alternatively, the AWS access key ID, and secret access key, and optionally session token can each be provided outside of the connection string using the --username, --password, and --awsIamSessionToken options instead, like so:

      mongo 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' --username <aws access key id> --password <aws secret access key> --awsIamSessionToken <aws session token>

When provided as command line parameters, these three options do not require percent encoding.

You may also set these credentials on your platform using standard AWS IAM environment variables (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-list). The mongo shell checks for the following environment variables when you use the MONGODB-AWS authentication mechanism:

    •   AWS_ACCESS_KEY_ID

    •   AWS_SECRET_ACCESS_KEY

    •   AWS_SESSION_TOKEN

If set, these credentials do not need to be specified in the connection string or via the explicit options to the mongo shell (i.e. --username and --password).

The following example sets these environment variables in the bash shell:

      export AWS_ACCESS_KEY_ID='<aws access key id>'
      export AWS_SECRET_ACCESS_KEY='<aws secret access key>'
      export AWS_SESSION_TOKEN='<aws session token>'

Syntax for setting environment variables in other shells will be different. Consult the documentation for your platform for more information.

You can verify that these environment variables have been set with the following command:

      env | grep AWS

Once set, the following example connects to a MongoDB Atlas cluster using these environment variables:

      mongo 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS'

  EXECUTE JAVASCRIPT AGAINST THE MONGO SHELL

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

isInteractive()

  USE --EVAL TO EXECUTE JAVASCRIPT CODE

You may use the --eval option to execute JavaScript directly from the command line.

For example, the following operation evaluates a JavaScript string which queries a collection and prints the results as JSON.

On Linux and macOS, you will need to use single quotes (e.g. ') to enclose the JavaScript, using the following form:

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

On Windows, you will need to use double quotes (e.g. ") to enclose the JavaScript, using the following form:

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

    •   mongo Shell Quick Reference

    •   mongosh Methods

    •   Legacy mongo Shell

    •   isInteractive()