Mage

Mage is a simple tool built on top of bin/magento to enhance your Magento 2 development experience. It provides shortcuts and custom functions to save you time and effort.

Note

Mage is a wrapper around your dev setup and n98-magerun2, not a replacement for them. See the FAQ.

Benefits of Using Mage

• Easy installation of Magento: create and install a Mage-OS, Magento Open Source or Adobe Commerce project in one command.
• Works from anywhere in a project: run mage from any nested folder, it finds the Magento root on its own.
• Environment aware: the same commands work on your machine, with Laravel Valet, Warden and DDEV.
• One place to add things: composer packages, git repositories, composer fragments from a json file, and generators for themes and modules.
• Everything else goes to bin/magento: any command mage does not know is passed on as is.

Installation

Download the script:

curl -O https://raw.githubusercontent.com/GrimLink/mage/main/mage && chmod +x mage

Alternatively, use wget:

wget https://raw.githubusercontent.com/GrimLink/mage/main/mage && chmod +x mage

Move it to a folder in your PATH, such as ~/.local/bin. Update it later with mage self-update, which also updates the templates.

Requirements

• bash 3.2 or newer, the version macOS ships with is enough.
• git, and curl or wget.
• jq for mage add <file>.json and mage add patch, for removing or updating packages by term, and for mage show modules and themes.

Commands

Run mage help for the full list. Anything mage does not know runs bin/magento, so mage cache:clean works as expected.

Command	Does
create	Create, install and set up a new project
setup	Reinstall Magento in an existing project
nuke	Permanently delete a project (database, environment, files)
backup	Back up the database, and optionally the media
restore	Restore a backup, and set it up for this device
sync	Pull the media, and optionally the latest backup, from a server
add	Add a package, git repository, composer fragment or generated code
add theme	Create a child theme
add module	Create a module
add hyva	Add the Hyvä Theme
add storeinfo	Add the Siteation StoreInfo modules
add patch	Add a composer patch, or all patches of a repository
add bfcache	Add the BFCache compatibility patches
add admin	Create an admin user
add customer	Create a customer
add store	Create a store view with its own domain
add i18n	Collect the phrases of a module or theme
add sample	Add the Luma or Koti sample data
del	Remove packages by name or term
upd	Update packages by name or term
enable, disable	Enable or disable modules by name or term
outdated	List the direct dependencies with a newer version
watch	Clean only the caches a file change affects
build	Build themes with their npm scripts, or watch one
log	Follow a log in var/log
reindex	Reindex, then clean the cache
clean	Clean caches and generated files (alias: purge)
info	Show the version, mode, urls and more of the project
open	Open a store view, the admin or the mail catcher in your browser
set	Change a setting, such as the CSP or full page cache
show	Show project information, such as the stores
run	Run n98-magerun2
help, version, self-update	Show help, show the version, update mage

Working from a nested folder

Mage looks for the Magento root (the folder with bin/magento and app/etc/di.xml) from the current folder upwards, and runs from there. So mage cache:clean works from app/code/Vendor/Module too. Outside a project only create, setup, help, version and self-update work.

Scripts and agents

Without a terminal, questions stop with an error instead of taking a default, -y or MAGE_YES=1 takes the defaults, and info and show can print json. See scripts and agents.

Configuration

Mage runs with sensible defaults, all of which can be changed in ~/.config/mage/config. See configuration.

Supported Platforms

Mage works on macOS and most Linux platforms, and detects these environments on its own, see environments:

• Local: services such as MySQL and OpenSearch on your machine.
• Laravel Valet
• Warden: supported with thanks to @tdgroot.
• DDEV

Contributing

We welcome contributions to Mage! Fork the repository, make your changes, and submit a pull request. See development for how the source is organised, built and tested.

Security

Mage runs as your own user, and its config is code you manage yourself. See the security policy for what mage does to stay safe, what is up to you, and how to report a vulnerability.

License

Mage is licensed under the MIT License. See the LICENSE file for details.