Magnolia CLI v5
This page describes the Magnolia CLI v5, its core components, and how to install it.
Plugin-based CLI
Magnolia CLI in version v5 is a plugin-based system. The purpose of this architecture is to offer developers enhanced flexibility, control, customization of commands by creating a plugin, and definition of their own project templates.
-
The CLI itself provides the core functionality and oversees the operation of the plugins. It uses a configuration file called
mgnl.config.js
, where you can configure the logger and the plugins. -
The plugins specified in this file are loaded by the CLI. To meet the requirements of your project, you can modify the file to use it with your own plugin collection.
Available plugins
For a list of all plugins, see the Plugins.
Pre-installed plugins
Several of the plugins are pre-installed:
-
Jumpstart plugin - allows you to download a project.
-
Generate plugin - allows you to generate a new plugin template.
Installing CLI
Prerequisites
Node.js
The Magnolia CLI tool requires Node.js.
To check the version of your node.js
installation, run the following command in a shell:
node -v
Node.js provides two branches, LTS
(recommended for long-term support) and Current
(providing the latest features).
Make sure you are running the latest version of the LTS
branch.
You can get it from Node.js downloads.
It may also be installed via package managers.
Java
Java is only required if you want to use the Start plugin, which starts Magnolia.
For Java installation details, see Get Java.
Installing
We recommend you use the Jumpstart plugin or install the Magnolia CLI locally at project level. This approach allows each project to:
-
maintain its unique configuration within the
mgnl.config.js
file, -
have separate plugins per project, and
-
to manage different versions of the CLI and the plugins more effectively.
Through the jumpstart plugin
This following command prompts you to choose a project template, automatically installs the CLI locally at the project level, and sets up the required files (package.json
and mgnl.config.js
) for you.
npx @magnolia/cli jumpstart
Locally
To install the latest production version locally at the project level, do the following:
-
Initialize the project if it’s not already set up:
npm init -y
-
Install the Magnolia CLI package:
npm install @magnolia/cli
-
Add the following script to
package.json
:{ ... "scripts": { ... "mgnl": "node node_modules/@magnolia/cli" } }
-
In
package.json
, set thetype
property tomodule
:{ ... "type": "module" }
-
Create the
mgnl.config.js
file, where you can configure your plugins:export default { plugins: [], logger: { filename: "./mgnl.error.log", fileLevel: "warn", consoleLevel: "debug" } };
Which versions are available?
To display a list of released versions of Magnolia CLI, enter the following command in a shell:
npm view @magnolia/cli versions
Besides a version list, the following command shows additional information about the Magnolia CLI package:
npm view @magnolia/cli
Testing the installation
To verify that the CLI has been successfully installed and to learn what it offers, use the following flags based on the type of installation.