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:

The add-plugin

The CLI also comes with the add-plugin command, which installs and registers a new plugin within your project.

Rather than a plugin, it’s more appropriate to view the add-plugin as a command, because it’s always available, even if a local mgnl.config.js exists.

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:

  1. Initialize the project if it’s not already set up:

    npm init -y

  2. Install the Magnolia CLI package:

    npm install @magnolia/cli

  3. Add the following script to package.json:

    {
  ...
  "scripts": {
    ...
    "mgnl": "node node_modules/@magnolia/cli"
  }
}

  4. In package.json, set the type property to module:

    {
  ...
  "type": "module"
}

  5. Create the mgnl.config.js file, where you can configure your plugins:

    export default {
  plugins: [],
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "warn",
    consoleLevel: "debug"
  }
};

Globally

To install the latest production version globally, run the following command:

sudo npm install @magnolia/cli -g (1)
1 The sudo part of the command may be required on Linux or macOS, depending on your permissions and the Node.js installation location.

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.

Locally

Prerequisite configuration

The CLI is installed in the project folder and the following is in the package.json file:

{
  "scripts": {
    "mgnl": "node node_modules/@magnolia/cli"
  }
}
Help
npm run mgnl -- -h
Version
npm run mgnl -- -V

Globally

Help
mgnl -h
Version
mgnl -V

Updating

Locally

To update the CLI installed locally, run the following npm command in your project directory.

npm update @magnolia/cli

Globally

To update the CLI installed globally, run the following npm command:

sudo npm update @magnolia/cli -g (1)
1 The sudo part of the command may be required on Linux or macOS, depending on your permissions and the Node.js installation location.
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia CLI docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules