mongosh(1)

OPTIONS
Use the following options to view and control various aspects of your MongoDB Shell.

GENERAL OPTIONS

mongosh --build-info

    Returns a JSON-formatted document with information about your mongosh build and driver dependencies.

    Example: View Build Information

    You can check the build information and driver dependencies of your mongosh binary by running the following command from your terminal:

          mongosh --build-info

    This command returns the following JSON-formatted document:

          {
            version: '1.10.1',
            distributionKind: 'packaged',
            buildArch: 'x64',
            buildPlatform: 'linux',
            buildTarget: 'unknown',
            buildTime: '2023-06-21T09:49:37.225Z',
            gitVersion: '05ad91b4dd40382a13f27abe1ae8c3f9f52a38f7',
            nodeVersion: 'v16.20.1',
            opensslVersion: '3.1.1',
            sharedOpenssl: true,
            runtimeArch: 'x64',
            runtimePlatform: 'darwin',
            deps: {
               nodeDriverVersion: '5.6.0'
             }
          }

mongosh --eval

    Evaluates a JavaScript expression. You can use a single --eval argument or multiple --eval arguments together.

    After mongosh evaluates the --eval argument, it prints the results to your command line. If you use multiple --eval statements, mongosh only prints the results of the last --eval.

    You can use the --json flag with --eval to return mongosh results in Extended JSON (https://www.mongodb.com/docs/manual/reference/mongodb-extended-json/) format. mongosh supports both --json=canonical and --json=relaxed modes. If you omit the mode, mongosh defaults to the canonical mode. The --json flag is mutually exclusive with --shell.

    Example: Format Output

    To get output suitable for automated parsing, use EJSON.stringify().

          mongosh --quiet  --host rs0/centos1104 --port 27500           --eval "EJSON.stringify(rs.status().members.map(             m => ({'id':m._id, 'name':m.name, 'stateStr':m.stateStr})));"   | jq

    After parsing with jq, the output resembles this:

          [
            {
               "id": 0,
               "name": "centos1104:27500",
               "stateStr": "PRIMARY"
            },
            {
               "id": 1,
               "name": "centos1104:27502",
               "stateStr": "SECONDARY"
            },
            {
               "id": 2,
               "name": "centos1104:27503",
               "stateStr": "SECONDARY"
            }
          ]

    EJSON has built in formatting options which may eliminate the need for a parser like jq. For example, the following code produces output that is formatted the same as above.

          mongosh --quiet  --host rs0/centos1104 --port 27500           --eval "EJSON.stringify( rs.status().members.map(             ({ _id, name, stateStr }) => ({ _id, name, stateStr })), null, 2);"

    Example: Multiple --eval Arguments

    To get a list of collections in the moviesDatabase, use multiple --eval statements:

          mongosh --quiet           --eval 'use moviesDatabase'           --eval 'show collections'           mongodb://localhost/

    Example: --json Option

    To return statistics about a collection in Extended JSON format using multiple --eval statements:

          mongosh --quiet --json=relaxed           --eval 'use <database-name>'           --eval 'db.<collection>.stats()'           mongodb://localhost/

mongosh --file, mongosh -f

    Runs a script from the command line without entering the MongoDB Shell console.

    For additional details and an example, see Execute a Script From the Command Line.

mongosh --help, mongosh -h

    Returns information on the options and use of the MongoDB Shell.

mongosh --nodb

    Prevents the shell from connecting to any database instances.

mongosh --no-quiet

    Disables the default --quiet option mode for non-interactive shell sessions. When specified, mongosh displays all messages during startup.

mongosh --norc

    Prevents the shell from sourcing and evaluating ~/.mongoshrc.js on startup.

mongosh --quiet

    Skips all messages during startup (such as welcome messages and startup warnings) and goes directly to the prompt.

    For non-interactive shell sessions, MongoDB enables --quiet by default. You can disable this behavior using --no-quiet.

mongosh --skipStartupWarnings

    Prevents mongosh from displaying server startup warnings when creating a session. To suppress all startup messages, use the --quiet option.

mongosh --shell

    Enables the shell interface. If you invoke the mongosh 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. The --shell flag is mutually exclusive with --json.

mongosh --verbose

    Increases the verbosity of the shell output during the connection process and when running commands.

mongosh --version

    Returns the MongoDB Shell release number.

STABLE API OPTIONS

mongosh --apiVersion

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

mongosh --apiStrict

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

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

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

CONNECTION OPTIONS

mongosh --host

    Specifies the name of the host machine where the mongod or mongos is running. If this is not specified, the MongoDB Shell 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 (--tls),

        The MongoDB Shell verifies that the hostname (specified in the --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, the MongoDB Shell does not match against the CN. If the hostname does not match the SAN (or CN), the MongoDB Shell shell fails to connect.

    For DNS seedlist connections (https://www.mongodb.com/docs/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, overrides any corresponding DNS-configured options set in the TXT record. Use of the mongodb+srv: connection string implicitly enables TLS (Transport Layer Security) / SSL (Secure Sockets Layer) (normally set with tls=true) for the client connection. The TLS (Transport Layer Security) option can be turned off by setting tls=false in the query string.

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

mongosh --port

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

  TLS OPTIONS

mongosh --tls

    Enables connection to a mongod or mongos that has TLS (Transport Layer Security) / SSL (Secure Sockets Layer) support enabled.

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

mongosh --tlsCertificateKeyFile

    Specifies the .pem file that contains both the TLS (Transport Layer Security) / SSL (Secure Sockets Layer) certificate and key for mongosh. 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 MongoDB Shell presents this certificate to the server.

    Starting in version 4.4, mongod / mongos logs a warning on connection if the presented X.509 certificate expires within 30 days of the mongod/mongos host system time.

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

mongosh --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 MongoDB Shell redacts 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 MongoDB Shell prompts for a passphrase.

    See TLS/SSL Certificate Passphrase.

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

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

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

mongosh --tlsCRLFile

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

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

mongosh --tlsAllowInvalidHostnames

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

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

mongosh --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.0, if you specify --tlsAllowInvalidCertificates when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS (Transport Layer Security) / SSL (Secure Sockets Layer) connection but is insufficient for authentication.

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

    If the MongoDB Shell shell (and other MongoDB Tools) runs with the --tlsAllowInvalidCertificates option, the shell (and other MongoDB Tools) do 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 (Transport Layer Security) / SSL (Secure Sockets Layer) certificates, see --tlsAllowInvalidHostnames.

    To learn more about TLS/SSL and MongoDB, see:

        •   Configure mongod and mongos for TLS/SSL (https://www.mongodb.com/docs/manual/tutorial/configure-ssl/)

        •   TLS/SSL Configuration for Clients (https://www.mongodb.com/docs/manual/tutorial/configure-ssl-clients/)

mongosh --tlsCertificateSelector

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

    When you import your private key, you must mark it as exportable. The Windows Certificate Import Wizard doesn't check this option by default.

    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.

    Starting in version 4.4, mongod / mongos logs a warning on connection if the presented X.509 certificate expires within 30 days of the mongod/mongos host system time.

mongosh --tlsDisabledProtocols

    Disables the specified TLS protocols. The option recognizes the following protocols:

        •   TLS1_0

        •   TLS1_1

        •   TLS1_2

        •   (Starting in version 4.0.4, 3.6.9, 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.

mongosh --tlsUseSystemCA

    Allows mongosh to load TLS certificates already available to the operating system's certificate authority without explicitly specifying the certificates to the shell. You cannot turn off this behavior. --tlsUseSystemCA can still be set for backward compatibility, but it has no effect.

    This flag applies to both MongoDB connections and OIDC identity provider connections.

AUTHENTICATION OPTIONS

mongosh --authenticationDatabase

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

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

mongosh --authenticationMechanism

    Specifies the authentication mechanism the MongoDB Shell uses to authenticate to the mongod or mongos. If you don't specify an authenticationMechanism but provide user credentials, the MongoDB Shell and drivers attempt to use SCRAM-SHA-256. If this fails, they fall back to SCRAM-SHA-1.

        •

            •   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 (Transport Layer Security) / SSL (Secure Sockets Layer) certificate authentication.

        •

            •   GSSAPI (Kerberos)

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

        •

            •   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 in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced) and MongoDB Atlas (https://www.mongodb.com/atlas/database).

        •

            •   MONGODB-OIDC (https://www.mongodb.com/docs/manual/core/security-oidc/) (OpenID Connect)

            •   External authentication using OpenID Connect. This mechanism is available in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced) and MongoDB Atlas (https://www.mongodb.com/atlas/database).

        •

            •   MONGODB-AWS (AWS IAM)

            •   External authentication using Amazon Web Services Identity and Access Management (AWS IAM) credentials. This mechanism is available in MongoDB Enterprise (http://www.mongodb.com/products/mongodb-enterprise-advanced) and MongoDB Atlas (https://www.mongodb.com/atlas/database).

mongosh --gssapiServiceName

    Specify the name of the service using GSSAPI/Kerberos (https://www.mongodb.com/docs/manual/core/kerberos/). Only required if the service does not use the default name of mongodb.

    This option is available only in MongoDB Enterprise.

mongosh --sspiHostnameCanonicalization

    Specifies whether or not to use Hostname Canonicalization.

    --sspiHostnameCanonicalization has the same effect as setting the CANONICALIZE_HOST_NAME:true|false key-pair in the authMechanismProperties portion of the connection string.

    If --sspiHostnameCanonicalization is set to:

        •   forwardAndReverse, performs a forward DNS lookup and then a reverse lookup. New in mongosh 1.3.0.

        •   forward, the effect is the same as setting authMechanismProperties=CANONICALIZE_HOST_NAME:true.

        •   none, the effect is the same as setting authMechanismProperties=CANONICALIZE_HOST_NAME:false.

mongosh --oidcFlows

    Specifies OpenID Connect flows in a comma-separated list. The OpenID Connect flows specify how mongosh interacts with the identity provider for the authentication process. mongosh supports the following OpenID Connect flows:

        •

            •   OpenID Connect Flow

            •   Description

        •

            •   auth-code

            •   Default. mongosh opens a browser and redirects you to the identity provider log-in screen.

        •

            •   device-auth

            •   mongosh provides you with a URL and code to finish authentication. This is considered a less secure OpenID Connect flow but can be used when mongosh is run in an environment in which it cannot open a browser.

    To set device-auth as a fallback option to auth-code, see the following example:

          mongosh 'mongodb://localhost/' --authenticationMechanism MONGODB-OIDC --oidcFlows=auth-code,device-auth

mongosh --oidcDumpTokens

    Specifies whether mongosh prints tokens with extra debugging information. Use this option for debugging purposes only.

    The --oidcDumpTokens option accepts the following values:

        •

            •   Value

            •   Description

        •

            •   redacted

            •   Default when you only set --oidcDumpTokens. Prints token debugging information with sensitive data redacted.

        •

            •   include-secrets

            •   Prints token debugging information including credentials that can potentially authenticate to database servers.

    The include-secrets value exposes credentials that attackers can use for authentication. Only use this option when unauthorized people cannot view the output of mongosh and the credentials are necessary for diagnostic purposes.

mongosh --oidcIdTokenAsAccessToken

    Specifies whether mongosh uses the ID token received from the identity provider instead of the access token. Use this option with identity providers that you can't configure to provide JWT (JSON Web Token) access tokens.

mongosh --oidcNoNonce

    By default, mongosh sends a nonce parameter during the OIDC (OpenID Connect) Authorization Code Flow.

    If you set the --oidcNoNonce option, mongosh does not send a nonce parameter. Use this option if your identity provider does not support nonce values as part of authorization.

mongosh --oidcRedirectUri

    Specifies a URI where the identity provider redirects you after authentication. The URI must match the configuration of the identity provider. The default is http://localhost:27097/redirect.

mongosh --oidcTrustedEndpoint

    Indicates that the current connection is to a trusted endpoint that is not Atlas or localhost. This ensures that access tokens are sent to the server. Only use this option when connecting to servers that you trust.

mongosh --browser

    Specifies the browser mongosh redirects you to when MONGODB-OIDC is enabled.

    This option is run with the system shell.

    Set --no-browser to disable opening browsers entirely.

mongosh --password, mongosh -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 the MongoDB Shell to prompt for a password, enter the --password option as the last option and leave out the argument.

mongosh --username, mongosh -u

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

SESSION OPTIONS

mongosh --retryWrites

    Enables Retryable Writes.

    By default, retryable writes are:

        •   enabled in mongosh

        •   disabled in the legacy mongo shell

    To disable retryable writes, use --retryWrites=false.

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

FIELD LEVEL ENCRYPTION OPTIONS

mongosh --cryptSharedLibPath

    The path to the Automatic Encryption Shared Library (https://www.mongodb.com/docs/manual/core/queryable-encryption/install-library/). The library must be version 8.2.0 or higher. Required to use automatic encryption for the mongosh shell session.

mongosh --awsAccessKeyId

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

    --awsAccessKeyId is required to enable Client-Side Field Level Encryption for the mongosh shell session. --awsAccessKeyId requires both 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.

mongosh --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 to enable Client-Side Field Level Encryption for the mongosh session. --awsSecretAccessKey requires both 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.

mongosh --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 to enable Client-Side Field Level Encryption for the mongosh 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.

mongosh --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 mongosh shell session. mongosh creates the specified namespace if it does not exist.

    --keyVaultNamespace requires both 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.