Magnolia CLI v4

Magnolia CLI is an npm package providing a command line interface (CLI) tool to set up and facilitate light development with Magnolia. This page describes how to configure and use its commands in CLI v4.

In version 4, the default prototypes are based on the Magnolia 6 UI framework and, therefore, the create commands generate Magnolia 6 UI definitions.

The legacy 5 UI prototypes are available as well, but are marked with -m5. You can generate the 5 UI definitions manually by using the -P or --prototype flag and specifying one of the -m5 prototypes available. The CLI can detect the Magnolia version in the current CLI setup and for versions below 6.2 it automatically creates definitions from the -m5 prototypes.

The commands of the Magnolia CLI package facilitate the creation of a light module skeleton: the folders and files that form a typical Magnolia light module. We assume that you are already familiar with some Magnolia basics of creating light modules, templates, and dialogs.

Configuration

Magnolia CLI is configured in these files/folders:

  • mgnl‑cli‑prototypes/ – A folder which contains the prototypes for template and dialog definitions and the README file.

  • mgnl‑cli.json – The configuration file defining the folders of the light module skeleton among other things.

Do not modify the package.json of your global installation, consider creating one local package.json for each project instead.

When you execute a CLI command, the system searches for the JSON configuration.

Global and local configurations

You can use the placeholder variables such as name and lightDevModuleFolder in prototypes files.

Global

The global configuration is created during the global installation of the Magnolia CLI package. On Linux or OS-X the global configuration files are typically located in the /usr/local/lib/node_modules/@magnolia/cli folder.

The CLI commands use the global configuration if no local configuration is found in the current directory or in its parent folders.

Local

For different projects you can create various local configurations with the customize-local-config command. This command creates local configuration files in the /wherever/you-have/executed/the-customize-local-config-command folder.

The local configuration is created as a copy of the current configuration (used during execution of the customize-local-config command), which you can edit to define project specific prototypes or dependencies.

When executing commands from within the local configuration folders or subfolders, the local configuration is used.

You cannot mix global and local configurations. When adding a local configuration it must be complete: it must contain the mgnl-cli.json file and the complete mgnl-cli-prototypes folder.

If Magnolia CLI finds the mgnl-cli.json file in the current or a parent directory, it expects to find the complete mgnl-cli-prototypes as well.

mgnl-cli.json

This JSON file contains basic configuration used when running Magnolia CLI commands. Here is a list of some of the properties in mgnl-cli.json:

Property Description

downloadFolder

The directory where Magnolia CLI stores downloaded artifacts.

We recommend you do not edit this property.

downloadUrl

The base URL of a Nexus repository used to download software artifacts such as a pre-configured Apache Tomcat servlet container and Magnolia webapps.

We recommend you do not edit this property.

downloadJars

A map of artifacts to be added to the WEB-INF/lib directory. Add artifacts to customize your webapps.

tomcatFolder

The name of the folder where the Magnolia bundled with Apache Tomcat is installed during the execution of the jumpstart command.

webapps.magnoliaAuthor webapps.magnoliaPublic

If set, these properties override the same properties in the magnolia.properties file by overwriting them.

You cannot set the magnolia.resources.dir property since Magnolia CLI overrides it.
These properties are used to update the magnolia.properties files (on both public and author) when you execute the jumpstart command.

availableWebapps

A list of possible webapps to choose from when executing jumpstart.

You can define additional webapp artifacts, if they are available in the Nexus repository specified by the downloadUrl.

https://git.magnolia-cms.com/projects/BUILD/repos/npm-cli/raw/lib/config/mgnl-cli.json?at=master

This version of mgnl-cli.json may not show all the parameters described below.

Prototypes

When you execute the create-app, create-block, create-component, create-content-type, create-light-module, create-page, create-virtual-uri commands, you create new files from the prototype files. These prototype files are located in the mgnl-cli-prototypes folder. For more information about the prototypes, see the subpage called Prototypes in CLI v4.

Commands

Universally available Magnolia CLI command options

Option Description

-h

Shows all the parameters and optional parameters (options) available for a command. When you execute a command with just the -h option, the command itself is not executed.

For example the command mgnl create-light-module -h will not create a light module structure in the current directory.

-v

Shows version information. When you execute a command with just this option, the command itself is not executed (same as entering mgnl -v).

add-availability

This command makes a component available to a page by:

  • Adding or updating the page template definition to enable the component for an area.

  • Adding the cms:area directive to the template script (if it is not already there).

The command only succeeds if the current directory (or the directory defined by the -p <path> parameter) is a light module with a minimal folder structure and if the page specified by the second argument exists.

Usage

mgnl add-availability <[module-id:]path-to-component> <path-to-page[@area]> [options]

Parameters

Parameter Description

<[module‑id:]path‑to‑component>

required

The component you want to make available.

Must at least contain the path to a component.

Can optionally start with the module identifier [module‑id:]. If the module identifier is not used, Magnolia CLI assumes the component belongs to the current light module or to the light module specified by the -p <path> option.

Magnolia CLI does not check the existence of the specified component.

<path‑to‑page[@area]>

required

The page you want to make the component available to.

The parameter starts with the path to the page template within the templates directory and it must end with an area name [@area]. If the area does not exist yet, the command adds an area to both the template script and the template definition.

If you do not specify an area, the command defaults to main area (if it exists) or creates main area (if it does not).

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the light module that contains the page template.

If the parameter is omitted, the command must be run in an existing light module folder.

-g

Add this parameter to autogenerate the component instead of providing plain availability.

Examples

This example makes a component from the mtk module available to the page named my-page in the area named main:

mgnl add-availability mtk:components/textImage pages/my-page@main

This example makes the component my-component available to the page my-page. Both the component and the page are part of the light module located at /Users/jdoe/dev/mgnl/light-modules/my-module/:

mgnl add-availability components/my-component pages/my-page@main -p /Users/jdoe/dev/mgnl/light-modules/my-module/

create-app

This command creates a content type and an app based on it (depending on the CLI prototype variant applied). The command creates the following two YAML files:

  • A content type definition file in the contentTypes folder of the light module.

  • An app descriptor in the apps folder of the light module.

The command succeeds only if the current directory (or the directory defined by the -p option) is a light module with at least a minimal folder structure.

The files which are created while executing this command are based on the files in the prototypes folder of your configuration. The files contain some standard code and example properties.

If you want to create just a content type, use the create-content-type command.

Usage

mgnl create-app <name> [options]

Parameters

Parameter Description

<name>

required

The name of the new app. The name cannot contain spaces.

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the light module where you want to create the app.

If you do not specify a path, the command must be run within an existing light module folder.

-P <name>

--prototype <name>

optional

The name of the prototype variant to create the app.

Example

mgnl create-app my-app -p /Users/johndoe/dev/mgnl/light-modules/my-module/
To start entering content in a newly created app, you first have to login again in the Admincentral.

In a production environment, you also need to set up security for the content types and apps you created.

create-block

In this CLI version, the block prototypes are not yet compatible with the migrated (6 UI) Content Editor module and Stories app.

The block definition created will be based on the 5 UI info.magnolia.editor.block.stock.FieldSetBlockDefinition.

If you want to use the 6 UI-native block definition (based on info.magnolia.block.BlockDefinition), you have to migrate the definition created by the command.

This command creates:

  • A block definition YAML file.

  • A template definition YAML file.

  • A freemarker template script.

The command succeeds only if the current directory (or the directory defined by the optional -p <path> parameter) is a light module with a minimal folder structure.

The files which are created when executing this command are built from the files in the prototypes folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a block.

Usage

mgnl create-block <blockName> [options]

Parameters
Parameter Description

<blockName>

required

The name of the new block definition. The block name cannot contain spaces.
Options
Short form Long form Description

-p <path>

--path <path>

optional

The path to the light module to add the new block to.

If you do not specify a path, you must run the command from an existing light module folder.

-P <name>

--prototype <name>

optional

The name of the prototype variant to create the block.
Example
mgnl create-block my-block

If you do not use the -p <path> option, you must run the command from an existing light module folder.

create-component

This command creates a new component template with (depending on the CLI prototype variant applied):

  • A template definition YAML file.

  • A freemarker template script.

  • A YAML dialog definition file.

Optionally, the component can be made available to a page using the -a option (internally calling the add-availability command).

The command succeeds only if the current directory (or the directory defined by the -p option) is a light module with a minimal folder structure.

The files which are created while executing this command are based on the files in the prototypes folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a component template.

Usage

mgnl create-component <name> [options]

Parameters

Parameter Description

<name>

required

The name of the new component template. The name cannot contain spaces.

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the light module you want to add the component template to.

If you do not specify a path, the command must be run within an existing light module folder.

-a <path‑to‑page[@area]>

--available <path-to-page[@area]>

optional

The page you want to make the component available to. When you specify this option, add-availability s called after the creation of component to make it available in a page area.

The parameter must start with the path to the page template within the templates directory and it must end with an area name. If the area does not exist yet, the command adds an area to both the template script and the template definition. If you do not specify an area, the command defaults to main area (if it exists) or creates main area (if it does not).

-g <path‑to‑page[@area]>

--autogenerate <path-to-page[@area]>

optional

Add this parameter to autogenerate the component instead of providing plain availability. As for the -a option, you must specify the target area and page.

-P <name>

--prototype <name>

optional

The name of the prototype variant to create the component. See prototype variants for the pre-configured variants available.

Example

mgnl create-component my-component -a pages/my-page@footer -p /Users/johndoe/dev/mgnl/light-modules/my-module/

create-content-type

This command creates a content type (depending on the CLI prototype variant applied). The content type is created as a YAML content type definition file in the contentTypes folder of the light module.

The command succeeds only if the current directory (or the directory defined by the -p option) is a light module with at least a minimal folder structure.

The file created while executing this command is based on a file in the prototypes folder of your configuration. The file contains some standard code and example properties.

Usage

mgnl create-content-type <name> [options]

Parameters

Parameter Description

<name>

required

The name of the new content type. The name cannot contain spaces.

Options

Short form Long form Description

-a

``

optional

Creates also a new app that references the content type. With the -a option, the command is functionally equivalent to the create-app command.

To start entering content in a newly created app, you first have to login again in the Admincentral

-p <path>

--path <path>

optional

The path to the light module where you want to create the content type. If you do not specify a path, the command must be run within an existing light module folder.

-P <name>

--prototype <name>

optional

The name of the prototype variant to create the content type.

Example

mgnl create-content-type foo -a -p /Users/johndoe/dev/mgnl/light-modules/my-module/

In a production environment, you also need to set up security for the content types and apps you created.

create-light-module

This command creates a new light module in the form of a set of empty light module folders and the following two files:

  • README.md, in the root folder of the module.

  • <moduleName>-messages_en.properties, in the i18n folder this command creates.

The name of the light module should be provided as a parameter when calling the command. The light module is created in the current directory or in the directory specified with the optional -p <path> parameter.

Usage

mgnl create-light-module [<moduleName>] [options]

Parameters

Parameter Description

<moduleName>

optional

(but recommended) The name of the new light module. Avoid spaces and special characters since this name is used as folder name.

If you do not specify a <moduleName>, the name of the current directory is set as the module’s name. This can be useful when the folder for the light module already exists.

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path of the parent directory for the new light module. If omitted, the new light module is created within the current folder.

-p <name>

--prototype <name>

The name of the prototype variant to create the light module. See prototype variants for the pre-configured variants available.

Examples

mgnl create-light-module my-module
mgnl create-light-module my-module -p ../../light-modules/
my-module/
├── decorations
├── dialogs
│ ├── components
│ └── pages
├── includes
│ └── README.txt
├── i18n
│ └── my-module-messages_en.properties
├── README.md
├── templates
│ ├── components
│ └── pages
└── webresources

create-page

This command creates a new page template with (depending on the CLI prototype variant applied):

  • A template definition YAML file.

  • A freemarker template script.

  • A YAML dialog definition file.

The command succeeds only if the current directory (or the directory defined by the optional -p <path> parameter) is a light module with a minimal folder structure. The files which are created when executing this command are built from the files in the prototypes folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a page template.

Usage

mgnl create-page <templateName> [options]

Parameters

Parameter Description

<templateName>

required

The name of the new page template. The template name cannot contain spaces.

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the light module to add the new template to.

If the parameter is omitted, the command must be run within an existing light module folder.

-P <name>

--prototype <name>

optional

The name of the prototype variant to create the page. See prototype variants for the pre-configured variants available.

Example

mgnl create-page my-page

If you do not use the -p <path> parameter, you must run the command from an existing light module folder.

 
info Using configuration at /usr/lib/node_modules/@magnolia/cli/lib/config/mgnl-cli.json
info Using prototypes at /usr/lib/node_modules/@magnolia/cli/lib/config/mgnl-cli-prototypes
info No path option provided, page template will be created in the current folder.
info Created /home/m/dev/my-module/templates/pages/my-page.ftl
info Created /home/m/dev/my-module/dialogs/pages/my-page.yaml
info Created /home/m/dev/my-module/templates/pages/my-page.yaml
info Page template created

create-virtual-uri

The command creates a virtual URI mapping configuration file (a YAML definition file) in the light module. The command succeeds only if the current directory (or the directory defined by the -p option) is a light module with a minimal folder structure. The file with a mapping is created in the virtualUriMappings folder. The folder is created by the command if it does not exist yet. The file created while executing this command is based on the files in the prototypes folder of your configuration.

Usage

mgnl create-virtual-uri <virtualUriName> [options]

Parameters

Parameter Description

<virtualUriName>

required

The name of the new URI configuration.

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the light module.

If no path is provided, then the current folder is assumed to be a light module and the virtual URI mapping is created there.

-f <uri>

--fromUri <uri>

optional

The pattern to be matched in the requested URI. Enclose the <uri> value in quotes. Example:

mgnl create-virtual-uri myFooMapping --fromUri '/foo' --toUri 'forward:/bar'

-t <prefix:uri>

--toUri <prefix:uri>

optional

A concrete URI that the request is mapped to. Enclose the <prefix:uri> value in quotes. Example:

mgnl create-virtual-uri myFooMapping --fromUri '/foo' --toUri 'forward:/bar'
The following action prefixes are supported: redirect, permanent and forward.

-P <name>

--prototype <name>

optional

The name of the prototype variant to create the mapping. The following prototypes are available: _default, regexp and empty. If the option is omitted, the mapping is created from the _default variant. The _default variant uses the DefaultVirtualUriMapping class. The regexp variant uses the RegexpVirtualUriMapping class. See java.util.regex.Pattern for the regex constructs.

No class is specified in the empty variant.

customize-local-config

Run this command to create a local configuration. It installs the files for the local configuration within the current directory, or within the directory defined by the optional -p <path> parameter.

Usage

mgnl customize-local-config [options]

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path into which the mgnl-cli-prototypes folder and mgnl-cli.json file are installed.

Example

mgnl customize-local-config -p ~/dev/mgnl/light-modules/

install

Downloads and installs one or more light modules from npm to the light module directory.

Usage

mgnl install <light-module-name> [options]

Parameters

Parameter Description

<light-module-name>

required

At least one name of a light module to be downloaded from npm. If you are installing more than one module from the repository, separate the module names with a space.

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the light-modules folder.

If you do not specify a path, Magnolia searches for the nearest apache-tomcat* folder and checks the value of the magnolia.resources.dir property as defined in the webapps of the folder.

Example

mgnl install google-maps-magnolia mgnl-bobby -p /Users/johndoe/dev/mgnl/light-modules/other-users-modules/

jumpstart

This command downloads, unpacks and pre-configures a Magnolia Tomcat server together with a specific webapp . It creates folders for the Tomcat server and for the light modules according to the configuration.

When you run this command, you are prompted to choose which Magnolia webapp you want to install:

? What Magnolia would you like to install?
1) magnolia-empty-webapp
2) magnolia-community-webapp
3) magnolia-community-demo-webapp
4) magnolia-dx-core-webapp
5) magnolia-dx-core-demo-webapp
Answer:

If you do not specify a webapp, the command downloads the latest released version of the magnolia-community-webapp.

If you choose a licensed webapp, you are prompted to enter access credentials to the Magnolia Nexus repository.

The jumpstart command installs the webapp within the current directory.

Usage

mgnl jumpstart [options]

Options

Short form Long form Description

-p <path>

--path <path>

optional

The -p option for the jumpstart command specifies the path to the light modules root folder which is observed for changes, not to an alternative location for the webapp to be installed. The path to the light modules root folder is set by the magnolia.resources.dir property in the magnolia.properties file of the installed Magnolia webapp.

If no path is provided:

  • A default folder named light-modules is created in the current folder.

  • Light modules are then created under this folder which is observed by Magnolia for changes.

  • The property is set to the following relative path: magnolia.resources.dir=${magnolia.home}/../../../light-modules

-m <version>

--magnolia-version <version>

optional

Use to choose a specific version of the Magnolia webapp. If not provided, the latest stable version of the specified webapp is downloaded.

Currently, the command with this option cannot download the maintenance release artifacts for which you need to login to the Nexus server.

-i <name>

--install-sample-module <name>

optional

If provided, a sample light module under the light modules root folder with the given name is created.

-s

--snapshot

optional

Downloads the latest snapshot development version of the specified webapp.

-w <webapp>

--webapp <webapp>

optional

Use to directly specify which Magnolia webapp you want to install.

The webapps available by default are:

  • magnolia-empty-webapp

  • magnolia-community-webapp

  • magnolia-community-demo-webapp

  • magnolia-dx-core-webapp

  • magnolia-dx-core-demo-webapp

You can change which webapps are listed by editing your mgnl-cli.json file.
If you do not specify a webapp using the -w option, you are prompted to choose one in the console.

Example

mgnl jumpstart -w magnolia-empty-webapp -m 6.1

When running the jumpstart command, make sure that the magnolia.war and tomcat.zip files do not already exist in the directory in which you are running the command. The presence of these files prevents the command from downloading new versions and the system simply installs from the existing files again.

See NPMCLI-100

help

Run the help command to list all the available commands of the Magnolia CLI package.

Usage

mgnl help [options]

Options

Short form Long form Description

<command>

optional

Shows basic help for the Magnolia CLI command specified as the option.

Without the option, a list of available CLI commands are displayed (same as entering mgnl -h).

tab-completion

Run the command to install or uninstall autocompletion for Magnolia CLI commands.

Usage

mgnl tab-completion <command>

Parameters

Parameter Description

install

Installs the required files for autocompletion.

uninstall

Removes the files which were previously installed during installation.

Example

mgnl tab-completion install

After successful installation, you see a list of files and an appended the tab-completion script.

search

Searches for Magnolia-related packages available from npm and returns their list together with the following information:

  • Package name.

  • Date and version of the latest commit.

  • Brief description of the package.

  • Contributor’s username.

Usage

mgnl search [options]

Options

Short form Long form Description

<query>

optional

The search query sent to the npm’s API (see NPMS API Docs). The query can contain multiple terms separated with commas and no spaces.

If you do not provide a query option, the command returns a list of all light modules.

Example

mgnl search language-switcherinfo 1 result foundinfo info 1) language-switcher-magnoliainfo 2017-02-25 1.0.5info Language Switcher - Component template for Magnolia CMSinfo magnolia

start

This command starts up Magnolia and displays the main log file (apache-tomcat/logs/catalina.out). Magnolia CLI looks in the current working directory or parent directories for the nearest folder with a name that starts with apache-tomcat. To stop Magnolia, use CTRL-C.

Get Java

Magnolia needs at least a Java Runtime Environment (JRE) to run. Check if there’s a version of Java already installed on your computer by opening the terminal or command prompt and typing java -version. If the system reports a version number, Java is installed on your computer.

See Certified stack to confirm that the version installed is supported.

For local development, use 17.0.12-zulu. Example installation using SDKMAN:

sdk install java 17.0.12-zulu

  • Windows

  • Mac

  • Linux

On Windows, you need a Java SE Development Kit (JDK). The Java Runtime Environment (JRE) is not enough because the Tomcat application server does not recognize it.

  • JRE is for users who run Java programs on their computers.

  • JDK is for developers who write Java-based applications.

Download and install JDK. By default, JDK is installed at C:\Program Files\Java\jdk-<version>\.

Instructions

Check for JAVA_HOME

  1. Open the command prompt.

  2. Type set and press ENTER.

  3. Find JAVA_HOME in the command output and verify that the path points to your JDK installation directory, for example, C:\Program Files\Java\jdk-<version>>.xx.

  4. If JAVA_HOME is missing or it points to the wrong directory, see Set JAVA_HOME.

Set JAVA_HOME

  1. Open the Command Prompt as an administrator.

  2. Set the path for JAVA_HOME.

    setx /m JAVA_HOME "path\to\Java\jdk" (1)
    1 Where path\to\Java\jdk is where your Java Development Kit is saved.

The set command creates the JAVA_HOME environment variable and sets its value to the JDK directory. The command is executed when Magnolia starts.

For Mac, you need to download or update to Java 11 or higher. After reviewing and agreeing to the terms of the license agreement, download the file, then double-click it to launch the installation wizard and follow the installation instructions.

The installation directory varies from one Linux system to another. On Debian-based distributions, JREs or JDKs are usually installed in /usr/lib/jvm/.

Usage

mgnl start [options]

Options

Short form Long form Description

-p <path>

--path <path>

optional

The path to the apache-tomcat folder. If no path is provided, Magnolia CLI checks in the current working directory or in the parent directories for the nearest folder with a name that starts with "apache-tomcat".

-d

optional

Does NOT ignore the open files limit check. The files limit check is ignored by default.

Example

mgnl start -p C:/magnolia-installations/magnolia-5.5.1/apache-tomcat-8.5.5
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