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 |
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 |
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 |
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 If Magnolia CLI finds the |
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 | ||||
---|---|---|---|---|---|
|
The directory where Magnolia CLI stores downloaded artifacts.
|
||||
|
The base URL of a Nexus repository used to download software artifacts such as a pre-configured Apache Tomcat servlet container and Magnolia webapps.
|
||||
|
A map of artifacts to be added to the |
||||
|
The name of the folder where the Magnolia bundled with Apache Tomcat is installed during the execution of the |
||||
|
If set, these properties override the same properties in the
|
||||
|
A list of possible webapps to choose from when executing jumpstart.
|
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
|
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.
|
Parameters
Parameter | Description |
---|---|
|
required The component you want to make available. Must at least contain the path to a component. Can optionally start with the module identifier Magnolia CLI does not check the existence of the specified component. |
|
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 If you do not specify an area, the command defaults to |
Options
Short form | Long form | Description |
---|---|---|
|
|
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. |
|
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
|
Parameters
Parameter | Description |
---|---|
|
required The name of the new app. The name cannot contain spaces. |
Options
Short form | Long form | Description |
---|---|---|
|
|
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. |
|
|
optional The name of the prototype variant to create the app. |
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 If you want to use the 6 UI-native block definition (based on |
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 |
---|---|
|
required The name of the new block definition. The block name cannot contain spaces. |
Options
Short form | Long form | Description |
---|---|---|
|
|
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. |
|
|
optional The name of the prototype variant to create the block. |
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.
Parameters
Parameter | Description |
---|---|
|
required The name of the new component template. The name cannot contain spaces. |
Options
Short form | Long form | Description |
---|---|---|
|
|
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. |
|
|
optional The page you want to make the component available to. When you specify
this option, 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 |
|
|
optional Add this parameter to
autogenerate the component instead of providing plain availability. As for the |
|
|
optional The name of the prototype variant to create the component. See prototype variants for the pre-configured variants available. |
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.
Parameters
Parameter | Description |
---|---|
|
required The name of the new content type. The name cannot contain spaces. |
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
`` |
optional Creates also a new app that references the content type. With the
|
||
|
|
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. |
||
|
|
optional The name of the prototype variant to create the content type. |
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 thei18n
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.
Parameters
Parameter | Description | ||
---|---|---|---|
|
optional (but recommended) The name of the new light module. Avoid spaces and special characters since this name is used as folder name.
|
Options
Short form | Long form | Description |
---|---|---|
|
|
optional The path of the parent directory for the new light module. If omitted, the new light module is created within the current folder. |
|
|
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.
Parameters
Parameter | Description |
---|---|
|
required The name of the new page template. The template name cannot contain spaces. |
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
|
optional The path to the light module to add the new template to.
|
||
|
|
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 |
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.
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
|
optional The path to the light module.
|
||
|
|
optional The pattern to be matched in the requested URI. Enclose the <uri> value in quotes. Example:
|
||
|
|
optional A concrete URI that the request is mapped to. Enclose the <prefix:uri> value in quotes. Example:
|
||
|
|
optional The name of the prototype variant to create the mapping. The following prototypes are available:
|
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.
install
Downloads and installs one or more light modules from npm to the light module directory.
Parameters
Parameter | Description |
---|---|
|
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. |
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.
Options
Short form | Long form | Description | ||||
---|---|---|---|---|---|---|
|
|
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:
|
||||
|
|
optional Use to choose a specific version of the Magnolia webapp. If not provided, the latest stable version of the specified webapp is downloaded.
|
||||
|
|
optional If provided, a sample light module under the light modules root folder with the given name is created. |
||||
|
|
optional Downloads the latest snapshot development version of the specified webapp. |
||||
|
|
optional Use to directly specify which Magnolia webapp you want to install. The webapps available by default are:
|
Example
mgnl jumpstart -w magnolia-empty-webapp -m 6.1
When running the See NPMCLI-100 |
tab-completion
Run the command to install or uninstall autocompletion for Magnolia CLI commands.
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.
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
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.
|
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. |
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 |
|
||
Set |
The |
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/
.
Options
Short form | Long form | Description |
---|---|---|
|
|
optional The path to the |
|
optional Does NOT ignore the open files limit check. The files limit check is ignored by default. |