Manage MongoDB servers and replica sets using JSON configurations!
Fetching latest commit…
Cannot retrieve the latest commit at this time.


mongoctl is a lightweight command line utility that simplifies the installation of MongoDB and management of MongoDB servers and replica set clusters. It is particularly useful if you maintain many MongoDB environments with lots of configurations to manage.

The core philosophy behind mongoctl is that all server and cluster configuration be defined declaratively as data, rather than procedurally as code or scripts. So, instead of typing shell commands with lots of options that you can never remember, or writing a bunch of shell scripts hard-coded with hosts, port numbers, and file-system paths, you simply define the universe of servers and clusters with JSON objects and pass them to mongoctl commands. Server and cluster definitions can reside in flat-files, behind a web-server (like Github for instance), or in a MongoDB database.


Usage: mongoctl [<options>] <command> [<command-args>]

A utility that simplifies the management of MongoDB servers and replica set clusters.

  -h, --help            show this help message and exit
  -v, --verbose         make mongoctl more verbose
  -n, --noninteractive  bypass prompting for user interaction
  --yes                 auto yes to all yes/no prompts
  --no                  auto no to all yes/no prompts
  --config-root CONFIGROOT
                        path to mongoctl config root; defaults to ~/.mongoctl

  Admin Commands:
    install-mongodb           - install MongoDB
    uninstall-mongodb         - uninstall MongoDB
    list-versions             - list all available MongoDB installations on this machine

  Client Commands:
    connect                   - open a mongo shell connection to a server
    dump                      - export MongoDB data to BSON files (using mongodump)
    restore                   - restore MongoDB (using mongorestore)

  Server Commands:
    start                     - start a server
    stop                      - stop a server
    restart                   - restart a server
    status                    - retrieve status of server
    list-servers              - show list of configured servers
    show-server               - show server's configuration
    tail-log                  - tails a server's log file
    resync-secondary          - Resyncs a secondary member

  Cluster Commands:
    configure-cluster         - initiate or reconfigure a cluster
    list-clusters             - show list of configured clusters
    show-cluster              - show cluster's configuration

    print-uri                 - prints connection URI for a server or cluster

See 'mongoctl <command> --help' for more help on a specific command.



  • Linux or MacOSX (mongoctl does not currently support Windows)
  • Python 2.6 or 2.7 (3.x not yet supported)
  • pip >= 1.0.2 (instructions on installing pip)
  • If planning to build MongoDB from source, i.e. with mongoctl install-mongodb --build-from-source: the scons tool (typically available in your package manager, such as apt, yum/dnf or brew.)

Supported MongoDB versions

mongoctl supports MongoDB versions >= 1.8.

Installing mongoctl

mongoctl is registered in the Python package index (PyPI).

Note: you may need to prefix these commands with sudo if you're using a system-level Python install (i.e. if running pip by itself results in permissions errors.) For example, sudo pip install mongoctl will install mongoctl to your system Python.

To install:

% pip install mongoctl

To update:

% pip install --upgrade mongoctl

To uninstall:

% pip uninstall mongoctl

Running mongoctl's test suite

To run mongoctl's test suite, execute the following command:

% python -m mongoctl.tests.test_suite

Note: executing the test suite will download and install a temporary copy of MongoDB (cached in a subfolder of mongoctl/tests) for use while testing.