MongooSh

A Mongoose command line shell.

Features:

• It's Mongoose! A much easier to understand wrapper around Mongo with less foot-guns
• Does not allow access to non-existent collections - trying to do db.nonExistantCollection.find() will error out that find is not callable on undefined
• Easily extendible command plugin system
• Customizable config files along with a plugin system to add your own functionality
• STFU about server messages on boot - e.g. "Oh no! You're not using XFS!"

Installation

Install globally by running

> npm install --global mongoosh

And connect to the test database with:

> mongoosh test

Built in commands

Command	Description
as <format> <query>	Display the output of a given query via a specific formatter. e.g. as json db.users.findOne()
db	The loaded Mongoose.model instance
edit <query>	Edit the output of a Mongoose query in your preferred editor, saving the result if changed
help	Built in command to list all other commands with their descriptions
settings	The settings structure MongooSh was booted with
use <db>	Switch to an alternative database by name
show <collections/databases>	List available collections or databases
.break	When in the process of inputting a multi-line expression, enter the .break command (or press Ctrl+C) to abort further input or processing of that expression
.clear	Resets the REPL context to an empty object and clears any multi-line expression being input
.exit	Close the I/O stream, causing the REPL to exit
.help	Show the list of REPL commands (commands starting with a dot)
.save	Save the current REPL session to a file e.g. .save ./file/to/save.js
.load	Load a file into the current REPL session e.g. .load ./file/to/load.js
.editor	Enter editor mode (Ctrl+D to finish, Ctrl+C to cancel)

Settings

Setting	Type	Default	Description
colors	Object	See object	Various color specifications, see object for full list
context	Object	See notes	The context passed to the REPL, see notes below
edit	Object	See below	Configuration for the edit command
edit.parse	Function	(JSON.parse)	How to convert the input back from the editor into a Mongo compatible object
edit.stringify	Function	(JSON.stingify using tabs)	How to convert a Mongo Object into text to pass to the editor
eval	Object	See below	Various settings to configure how the command evaluator works
eval.commands	Object<Function>	See notes	Lookup object of internal commands
inspect	Object	See below	Settings passed to util.inspect when showing the output of an object
formatters	Object	See notes	Definition list of output modes, see prompt.outputMode setting or as command
inspect.depth	Number	2	The maximum depth to inspect to before digesting the remaining data
inspect.colors	Boolean	true	Whether to use colors when inspecting
mongoose	Object	See below	Various options used when connecting to Mongoose
mongoose.autoConnect	Boolean	true	Whether to automatically connect to Mongoose and set up db
mongoose.database	String		The database to connect to, if blank use use <database> to switch
mongoose.host	String	'localhost'	Host to connect to
mongoose.uri	String		Alternate method to specify a full Mongo URI (overrides other settings)
paths	Object	See below	Object storing various paths to load assets from
paths.commands	Array<String>	['${__dir}/commands/*.js']	Array of globs to load command plugins from
prompt	Object	See below	Various settings to tweak the MongooSh prompt appearance
prompt.history	Boolean / String	'.mongoosh.history'	Path to a file to store session history. Use boolean false to disable
prompt.ignoreUndefined	Boolean	true	Don't print output of commands that return undefined
prompt.preview	Boolean	true	Show command output previews
prompt.text	String	'> '	The prompt text to display
prompt.outputMode	String	'inspect'	How to output data to the prompt, uses a method in formatters
tables.headerBold	Boolean	true	Whether the header row on table output should be bold-face
tables.headerUnderline	Boolean	true	Underline the header area of table output

Notes:

• The context setting is populated with the global objects specified in Built in commands
• eval.commands is a lookup object containing internal commands to the function called. see Extending MongooSh for more information
• formatters is an object of output formatters to print objects. Valid options are inspect (using util.inspect()), json - raw JSON output, jsonTabs - tabbed JSON output, jsonSpaces - 2 space indentation format
• All color.* keys are strings representing any valid Chalk methods separated by spaces e.g. 'blue', 'bold underline yellow'

Custom config / imports

MongooSh supports several configuration file types which are loaded when running the command line shell.

• ~/.mongoosh.json - Loaded as simple JSON and merged with the global settings
• ~/.mongoosh.js - Imported as a CJS script, the contents of module.exports is merged with the global settings
• ~/.mongoosh.mjs - Imported as a ESM module, the output of exports default is merged with the global settings

Extending MongooSh

There are multiple ways to extend MongooSh, all of them revolve around injecting script into the config files (either .js or .mjs variants).

Extend commands directly

To add your own commands or other functionality simply extend the context passed to any of the config imports.

All custom commands and config files are called with the context of mongooshContext which is an object composed of:

Key	Type	Description
repl	Repl	The active Node REPL instance
settings	Object	POJO for the active session settings

The context can be mutated by any plugin directly.

For example to define the foo custom command add the following to ~/.mongoosh.js:

// If the config returns a function it is called with the context `mongooshContext`
module.exports = function() {

    // Glue `foo` into the custom commands object
    this.settings.eval.commands.foo = function(bar, baz) {
        console.log('You tried to run the Foo command with arguments', bar, baz);
    };

    // Glue some help text to describe the command in `help`
    this.settings.eval.commands.foo.description = 'Command that does something';

};

Define a globbable directory for commands

Extend the settings.paths.commands array to point to your own custom directory of commands.

# In ~/.mongoosh.js
module.exports = function() {
    this.settings.paths.commands.push('/home/user/my/dir/of/commands/*.js');
};

# In /home/user/my/dir/of/commands/awesome.js
export let description = 'My awesome command';

export default function(foo, bar, baz) {
    // ... //
}