Configure Settings Using the API

On this page

Syntax

Behavior
Examples

The config API provides methods to examine and update the mongosh configuration. Updates made using the config API persist between sessions.

Note

The config API can be used within the mongosh command line interface. It has no effect in the embedded Compass shell.

Syntax

Print the current mongosh configuration:

config

Return the current value for <property>:

config.get( "<property>" )

Change the current setting of <property> to <value>:

config.set( "<property>", <value> )

Reset a <property> to the default value:

config.reset( "<property>" )

Supported `property` parameters

Key	Type	Default	Description
`disableLogging`	boolean	`false`	Specifies whether MongoDB Shell writes log entries.
`displayBatchSize`	integer	20	The number of items displayed per cursor iteration
`enableTelemetry`	boolean	`true`	Enables sending anonymized tracking and diagnostic data to MongoDB.
`editor`	string	`null`	Designates an editor to use within the `mongosh` console. Overrides the `EDITOR` environment variable if set.
`forceDisableTelemetry`	boolean	`false`	Only available in the global configuration file. When true, users cannot enable telemetry manually.
`historyLength`	integer	1000	The number of items to store in `mongosh` REPL's history file.
`inspectCompact`	integer or boolean	3	The level of inner elements that `mongosh` outputs on a single line. Short array elements are also grouped together on a single line. If set to `false`, `mongosh` outputs each field on its own line.
`inspectDepth`	integer or Infinity	6	The depth to which objects are printed. Setting `inspectDepth` to `Infinity` (the javascript object) prints all nested objects to their full depth.
`logCompressionEnabled`	boolean	false	Specifies whether MongoDB Shell compresses log files. When this value is `true`, MongoDB Shell uses gzip to compress logs. See Enable Log Compression.
`logLocation`	string	Depends on your operating system. See View Shell Logs.	Directory where MongoDB Shell writes log files. Specify an absolute filepath. See Specify Log File Location.
`logMaxFileCount`	integer or Infinity	100	Maximum number of log files that the MongoDB Shell retains. After the MongoDB Shell reaches the maximum log file count, it starts deleting the oldest log files until the count is below the threshold. See Modify Maximum Log File Count.
`logRetentionDays`	integer or Infinity	30	Number of days that MongoDB Shell log files are retained. If this value is set to `Infinity`, log files are not deleted based on age. To prevent log storage from growing too large, always specify at least one log retention criterion. See Log Retention.
`logRetentionGB`	float or Infinity	Unset	Maximum amount of space in gigabytes used for MongoDB Shell logs. If the combined size of MongoDB Shell logs exceeds this value, log files are deleted starting with the oldest logs. If this value is set to `Infinity`, log files are not deleted based on storage size. To prevent log storage from growing too large, always specify at least one log retention criterion. See Log Retention.
`redactHistory`	string	`remove`	Controls what information is recorded in the shell history. Must be one of: `keep`: Retain all history. `remove`: Remove lines which contain sensitive information. `remove-redact`: Redact sensitive information.
`showStackTraces`	boolean	`false`	Controls display of a stack trace along with error messages.
`snippetAutoload`	boolean	`true`	If `true`, automatically load installed snippets at startup.
`snippetIndexSourceURLs`	string	MongoDB Repository	A semicolon-separated list of URLs that link to a snippet registry.
`snippetRegistryURL`	string	npm Registry	The npm registry used by the `mongosh` npm client that installs snippet.

Behavior

Remove or Redact Sensitive Information From History

mongosh makes "best-effort" attempts to match patterns that normally correspond to certain kinds of sensitive information.

There are patterns that match:

Certificates and keys
Email addresses
Generic user directories
HTTP(s) URLs
IP addresses
MongoDB connection strings

Certain operations, such as connect(), are considered inherently sensitive. If redactHistory is set to remove or remove-redact, lines with these operations will be removed from the command line history.

Other operations, like find(), sometimes have sensitive information like email addresses. The shell history will retain these lines as entered unless redactHistory is set to remove-redact.

Behavior with Configuration File

Settings specified with the config API:

Override settings specified in the configuration file.
Persist across restarts.

Example

Consider the following configuration file that sets the inspectDepth setting to 20:

mongosh:
  inspectDepth: 20

During your mongosh session you run the following command to set inspectDepth to 10:

config.set( "inspectDepth", 10 )

The value of inspectDepth becomes 10, and will remain 10 even when mongosh is restarted.

Examples

Update Number of Items Returned by a Cursor

Consider viewing a collection with a number of large documents. You can update the batchSize to limit the number of items returned by a cursor.

config.set("displayBatchSize", 3)

Future db.collection.find() operations will only return 3 documents per cursor iteration.

Turn On Stack Traces

Enable stack traces to see more detailed error reporting.

config.set("showStackTraces", true)

The output differs like this:

// showStackTraces set to 'false'
Enterprise> db.orders.find( {}, { $thisWontWork: 1 } )
MongoError: FieldPath field names may not start with '$'.
// showStackTraces set to 'true'
Enterprise> db.orders.find( {}, { $thisWontWork: 1 } )
Uncaught:
MongoError: FieldPath field names may not start with '$'.
    at MessageStream.messageHandler (/usr/bin/mongosh:58878:20)
    at MessageStream.emit (events.js:315:20)
    at MessageStream.EventEmitter.emit (domain.js:548:15)
    at processIncomingData (/usr/bin/mongosh:57954:12)
    at MessageStream._write (/usr/bin/mongosh:57850:5)
    at writeOrBuffer (_stream_writable.js:352:12)
    at MessageStream.Writable.write (_stream_writable.js:303:10)
    at Socket.ondata (_stream_readable.js:719:22)
    at Socket.emit (events.js:315:20)
    at Socket.EventEmitter.emit (domain.js:548:15)

Call `config` API from outside `mongosh`

You can call the config API from the command line using --eval with mongosh. In this case the --nodb option means mongosh will update without connecting to a MongoDB database.

Important

You must use different quotation marks for the --eval expression and the config property. That is, single quotes for one and double quotes for the other.

mongosh --nodb --eval 'config.set("enableTelemetry", true)'

mongosh returns additional information along with the result of the API call.

Current Mongosh Log ID:      609583b730e14918fa0d363f
Using MongoDB:               undefined
Using Mongosh Beta:  0.12.1
For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/
Setting "enableTelemetry" has been changed

Redact Sensitive Information

Compare the recalled history when redactHistory is set to remove-redact or remove.

Set redactHistory to remove-redact mode and enter a query containing an email address.

config.set( "redactHistory", "remove-redact" )
db.contacts.find( {"email": "customer@clients.com" } )

When you press the up arrow to replay the last command the email address is redacted.

db.contacts.find( {"email": "<email>" } )  // Redacted

Set redactHistory to remove mode and enter a query containing an email address.

config.set( "redactHistory", "remove" )
db.contacts.find( {"email": "customer@clients.com" } )

When you press the up arrow to replay the last command the email address is present.

db.contacts.find( {"email": "customer@clients.com" } )

The shell history reflects the changes. (Note that this stores the most recent input first.)

db.contacts.find( {"email": "customer@clients.com" } )
config.set( "redactHistory", "remove" )
db.contacts.find( {"email": "<email>" } )
config.set( "redactHistory", "remove-redact" )

Reset a Configuration Setting to the Default Value

If you modified a configuration setting and want to reset it to the default value, use config.reset( "<property>" ).

Change the value of the historyLength setting to 2000:
```
config.set("historyLength", 2000)
```
Verify the updated value for historyLength:
```
config.get("historyLength")
```
Reset the historyLength setting to the default value of 1000:
```
config.reset("historyLength")
```
Verify the updated value for historyLength:
```
config.get("historyLength")
```

Back

Configure Settings

Use a Configuration File