Magnolia CLI v2
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 install, set up, configure and use the commands in the version 2 branch.
If you are using a Magnolia CLI version 3 or version 4, see the appropriate version pages. |
To install Magnolia CLI, see the Getting Started page.
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:
Files
|
A folder which contains the prototypes for template and dialog definitions and the README file. For further details see prototypes. |
|
The configuration file defining the folders of the light module skeleton and some other things. |
When a CLI command is executed, the system searches for the JSON configuration.
Do not modify the |
Global and local configurations
|
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 configurations which are used when running the Magnolia CLI commands. Here is a partial list of the properties which you might want to edit:
Property | Meaning | Used by | ||||
---|---|---|---|---|---|---|
|
The URL used to download the bundle.
|
The |
||||
|
A map of artifacts to be added to the |
The |
||||
|
The name of the folder where the Magnolia bundled with Tomcat is installed during the execution of the jumpstart command. |
The |
||||
|
If set these properties override the same properties in the magnolia.properties file by overwriting them there.
|
The |
||||
|
The folders which are created for a light module. |
The |
See the Magnolia CLI v2 mgnl.cli JSON. This version of mgnl.json may not include all parameters described below. |
Prototypes
When executing either the create-page
or the create-component
command, new files are created from the prototype files. These prototype
files are located in the mgnl-cli-prototypes
folder.
<configuration>/mgnl-cli-prototypes/
├── README.md.tpl
├── component
│ ├── definition.yaml
│ ├── dialog.yaml
│ └── template.ftl
└── page
├── definition.yaml
├── dialog.yaml
└── template.ftl
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
Short form | Description | ||
---|---|---|---|
|
REQUIRED The component you want to make available. Must at least contain the path to a 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
|
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
|
The path to the light module that contains the page template.
|
||
|
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-component
This command creates a new component template including:
-
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 | ||
---|---|---|---|
|
The name of the new component template.
|
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
--path <path> |
optional The path to the light module you want to add the component template to. If no path is specified, 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,
|
|||
`-g <path‑to‑page[@area]> ` |
optional Add this parameter to autogenerate the component instead of providing plain availability. As for the |
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.
|
create-page
This command creates a new page template including:
-
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 | ||
---|---|---|---|---|
`-p <path> ` |
|
optional The path to the light module to add the new template to.
|
Example
mgnl create-page my-page
If you do not use the |
INFO: No path option provided, page template will be created in the current folder.
DONE: Page template created
INFO: /Users/jdoe/dev/mgnl/light-modules/my-module/templates/pages/my-page.yaml created
INFO: /Users/jdoe/dev/mgnl/light-modules/my-module/templates/pages/my-page.ftl created
INFO: /Users/jdoe/dev/mgnl/light-modules/my-module/dialogs/pages/my-page.yaml created
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 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 bundle. It creates folders for the Tomcat server and for the light modules according to the configuration.
By default the command downloads the latest released version of the
magnolia-community-demo-bundle
. Use the -e
parameter to get the EE
Pro demo bundle (magnolia-enterprise-pro-demo-bundle
) instead. These
bundles contain the Magnolia
Travel Demo. Chose a specific
version by providing the -m
parameter.
The jumpstart command installs the bundle within the current directory.
You may remove the magnolia.zip
file once the installation is
complete.
Options
Short form | Long form | Description | ||
---|---|---|---|---|
|
|
optional The
|
||
|
|
optional The desired version of the Magnolia bundle. If not provided, defaults to the latest version of the chosen bundle (magnolia-community-demo-bundle or magnolia-enterprise-pro-demo-bundle).
|
||
|
|
optional If provided, a sample light module under the light modules root folder with the given name is created. |
||
|
optional (since 1.0.5) Downloads a magnolia-enterprise-pro-demo-bundle. Requires enterprise credentials to Magnolia Nexus. |
|||
|
optional (since 2.2.0) Downloads a Magnolia Cloud bundle. Requires enterprise credentials to Magnolia Nexus. |
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 https://api-docs.npms.io).
|
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, simply use
CTRL-C.
Options
Short form | Long form | Description |
---|---|---|
|
|
optional The path to the apache-tomcat folder. If no path is specified, Magnolia CLI looks in the current working directory or in the parent directories for the nearest folder with a name that starts with "apache-tomcat". |
|
optional Does NOT ignore the open files limit check. The files limit check is ignored by default. |
tab-completion
Run the command to install or uninstall autocompletion for Magnolia CLI commands.