Skip to content

CLI Commands

Jump to bottom
Brandon Marlowe edited this page Aug 16, 2026 · 1 revision

Overview

MMPM is both a Command Line Interface and User Interface designed to simplify managing your MagicMirror and its modules (packages).

Upgrading from 4.x? Several commands changed in 5.0.0: install is now add, mm-ctl is now mm (alias: magicmirror), mm-pkg is now custom-pkg, and the ui, mm, and open subcommands use verbs instead of flags (e.g. mmpm ui install instead of mmpm ui --install).

version

Display MMPM's version:

mmpm version

update

Initialize the package list and check for updates (similar to apt update):

mmpm update

upgrade

Upgrade packages/applications which have upgrades available:

mmpm upgrade                    # upgrade everything with an available upgrade
mmpm upgrade MMM-mmpm           # upgrade specific package(s)
mmpm upgrade MagicMirror        # MagicMirror and mmpm are valid names, too
mmpm upgrade -y                 # skip confirmation prompts
mmpm upgrade --force MMM-mmpm   # force an upgrade even if none is listed as available

search

Search for keywords or categories:

mmpm search sports
mmpm search weather --title-only

add/remove

Add (install) or remove a MagicMirror package:

mmpm add -y MMM-mmpm # alias `mmpm install`
mmpm remove -y MMM-mmpm

list

List packages or categories:

mmpm list --installed        # currently installed packages
mmpm list --all              # list all packages
mmpm list --categories       # list all package categories
mmpm list --upgradable       # list packages/applications which have available upgrades

show

Display extra detail about a package:

mmpm show MMM-mmpm
mmpm show --remote MMM-mmpm   # include details from the GitHub/GitLab/Bitbucket API

ui

Manage the MMPM web interface (pm2 is required):

mmpm ui install -y   # install the UI
mmpm ui url          # display the address of the UI
mmpm ui status       # display the status of the UI processes
mmpm ui start        # start the UI
mmpm ui stop         # stop the UI
mmpm ui restart      # restart the UI
mmpm ui reinstall -y # reinstall the UI
mmpm ui remove -y    # remove the UI

mm

Control MagicMirror itself (alias: mmpm magicmirror). Hiding/showing modules requires MMM-mmpm to be installed:

mmpm mm status       # list all active modules and their keys
mmpm mm hide 4       # hide the module with key '4' (keys are shown by 'status')
mmpm mm show 4       # show the module with key '4'
mmpm mm start        # start MagicMirror (works with pm2 and docker-compose)
mmpm mm stop         # stop MagicMirror
mmpm mm restart      # restart MagicMirror
mmpm mm install      # install MagicMirror
mmpm mm remove       # remove MagicMirror

env

Display the current MMPM environment settings:

mmpm env
mmpm env --describe   # include a description of each environment variable

open

Edit configuration files and open web pages:

mmpm open env           # open the MMPM env configuration file in your $EDITOR
mmpm open config        # open the MagicMirror config.js in your $EDITOR
mmpm open css           # open the MagicMirror custom.css in your $EDITOR
mmpm open ui            # open the MMPM UI in your browser
mmpm open magicmirror   # open MagicMirror in your browser
mmpm open mm-wiki       # open the MagicMirror wiki page
mmpm open mm-docs       # open the MagicMirror documentation
mmpm open mmpm-wiki     # open the MMPM wiki page

guided-setup

Interactive setup of MMPM — configures your environment and offers to install the UI and MMM-mmpm module. Can be re-run at any time:

mmpm guided-setup

doctor

Diagnose common problems with your MMPM, MagicMirror, and package installations. Checks your environment settings, dependencies, database, installed packages, running services, and remote API health — each finding includes a suggested fix. Read-only, safe to run anytime:

mmpm doctor          # run all checks; exits non-zero if any check fails
mmpm doctor --json   # output the results as JSON

custom-pkg

Add custom packages to your local database (similar to add-apt-repository). See Custom Packages for more details.

mmpm custom-pkg add       # interactively add a custom package
mmpm custom-pkg remove -y <package>

rollback

Roll back an installed package to a previously installed version (recorded in mmpm.lock):

mmpm rollback MMM-mmpm             # roll back to the previously installed version
mmpm rollback --history MMM-mmpm   # show the recorded version history
mmpm rollback --select MMM-mmpm    # choose a version to roll back to

sync

Clone, checkout, and install packages to match the versions recorded in ~/.config/mmpm/mmpm.lock:

mmpm sync

logs

Display MMPM logs:

mmpm logs
mmpm logs --tail   # follow the logs live
mmpm logs --zip    # archive the log files (useful for bug reports)

completion

See Tab Completion for more details.

db

Display information about the database:

mmpm db --info   # display metadata including when the database was last updated
mmpm db --dump   # dump the entire database to stdout in JSON format

Clone this wiki locally