Command line interface (CLI) commands

Edit

Improvements?

Let us know by posting here.

Since version 5.7.5, Concrete CMS offers a set of commands that can be run in a terminal console (including SSH sessions, bash and sh shells, Windows command prompts, ...).

  Note: for Windows systems, please replace all the / characters with \.

In order to run these CLI commands, open a terminal console and make the Concrete webroot folder the current directory (eg. the one that contains the index.php file); making that folder the current directory is not mandatory but it's useful for people that read this document only partially.

To have a list of all the available CLI commands, type the following:

concrete/bin/concrete5 list
  Note: if you are under *nix or MacOS X and you get a Permission denied error, you may need to run chmod a+x concrete/bin/concrete5.

A full list of commands with a short description of each will be printed. You can note that every command starts with a prefix (called namespace).

Only the commands with the c5 namespace are described here (you can list these commands alone by typing concrete/bin/concrete5 list c5). Other currently available namespaces are:

To get the full syntax of each command it's enough to type --help after the command name. For instance:

concrete/bin/concrete5 c5:job --help

prints out this:

Usage:
  c5:job [options] [--] [<jobs>]...

Arguments:
  jobs        Jobs to run (separate multiple jobs with a space)

Options:
      --set   Find jobs by set instead of job handle
      --list  List available jobs
...

In case you want to run any of the CLI commands under different environment configuration settings than the default ones, pass the --env envname option to the script for example as follows:

concrete/bin/concrete5 c5:update --env envname

For more information on how to setup different environment configurations, please check at the documentation section about environment specific configurations.

Available c5 commands

Here's a description of the available commands offered by Concrete.

Where not specified, the return codes of all the commands are 0 if the operation was successful or 1 in case of errors.

Install Concrete with c5:install

(available since Concrete 5.7.5)

Use this command to install Concrete via the command line. Here's a sample usage:

 concrete/bin/concrete5 c5:install --db-server=DB_SERVER --db-username=DB_USERNAME --db-password=DB_PASSWORD --db-database=DB_NAME --site=SITE_NAME --starting-point=STARTING_POINT --admin-email=EMAIL --admin-password=PASSWORD --default-locale=LOCALE

Where:

  • DB_SERVER is the host name with the database server (if it's available on a custom port, for instance 3333, simply add :3333)
  • DB_USERNAME is the username to be used to access the database server
  • DB_PASSWORD is the password associated to DB_USERNAME
  • DB_NAME is the name of the database to use (it must exist and it must be empty)
  • SITE_NAME is the name to give to the new Concrete installation (will be shown for instance in the page titles)
  • STARTING_POINT specify which set of initial data should be installed. By default Concrete comes with elemental_full and elemental_blank
  • EMAIL is the email to associate to the admin account that will be created on the new Concrete installation
  • PASSWORD is the password to assign to the admin account that will be created on the new Concrete installation
  • LOCALE (this is optional) is the code of the defauld site language (by default it's en_US)

Options since Ver 8.0.0

 concrete/bin/concrete5 c5:install [--db-server DB-SERVER] [--db-username DB-USERNAME] [--db-password DB-PASSWORD] [--db-database DB-DATABASE] [--site SITE] [--canonical-url CANONICAL-URL] [--canonical-ssl-url CANONICAL-SSL-URL] [--starting-point STARTING-POINT] [--admin-email ADMIN-EMAIL] [--admin-password ADMIN-PASSWORD] [--demo-username DEMO-USERNAME] [--demo-password DEMO-PASSWORD] [--demo-email DEMO-EMAIL] [--language LANGUAGE] [--site-locale SITE-LOCALE] [--config CONFIG] [--attach] [--force-attach] [-i|--interactive]

Here's a sample session:

$ concrete/bin/concrete5 c5:install ...
5%: Starting installation and creating directories.
10%: Creating database tables.
15%: Adding admin user.
20%: Installing permissions & workflow.
23%: Creating home page.
25%: Installing attributes.
30%: Adding block types.
33%: Adding gathering data sources.
36%: Page type basic setup.
38%: Adding themes.
40%: Installing automated jobs.
45%: Installing dashboard.
55%: Installing login and registration pages.
57%: Adding image editor functionality.
60%: Configuring site.
65%: Importing files.
70%: Adding pages and content.
90%: Setting up site permissions.
95%: Finishing.
Installation Complete!

$

Reset a Concrete installation with c5:reset

(available since Concrete 5.7.5)

In order to fully reset a Concrete installation, you can use this command. Since it's very dangerous (it will erase all the site contents and all the database tables), you have to specify the optional argument --force (or -f).

Here's a sample session:

$ concrete/bin/concrete5 c5:reset -f
Listing tables... done.
Dropping foreign key QueueMessages.queuemessages_ibfk_1... done.
Dropping table AreaLayoutColumns... done.
[...]
Dropping table gaPage... done.
Deleting file application/config/app.php... done.
Deleting file application/config/database.php... done.
Deleting directory application/config/generated_overrides... done.
Deleting directory application/config/doctrine... done.
Deleting directory application/files... done.
Creating directory application/files... done.
Creating empty file application/files/index.html... done.

$

Generate IDE symbols with c5:ide-symbols

(available since Concrete 5.7.5)

This command is very useful for developers that use an intelligent editor (IDE) to develop for Concrete. The main problem is that Concrete comes with facades and other proxy classes that are not recognizable by editors (for instance, the \Core class). Furthermore, IDEs don't know the results of IoC calls (for instance, they can't determine the class name resulting from \Core::make('config')).

By calling

concrete/bin/concrete5 c5:ide-symbols

you'll have two files that can help IDE auto-completion features. The first file created (saved as concrete/src/Support/__IDE_SYMBOLS__.php) defines the facade classes and their methods (so that IDE can suggest you the available methods after writing \Core::).

The second file created (saved as concrete/src/Support/.phpstorm.meta.php) helps IDEs to determine the type of the results of calls like \Core::make('config'). Please note that at the moment this file is only recognized by PhpStorm (but a feature request has been submitted for Eclipse PDT - please vote for it).

Configure Concrete with c5:config

(available since Concrete 5.7.5)

This CLI command is useful to change the (many) configuration options that can't be managed in the dashboard (even if some add-ons can give you access to them). It's also very handy if you want to configure your Concrete installation using console scripts without manually editing the configuration files under /application/config.

The c5:config can both set and retrieve all the Concrete parameters.

For instance:

concrete/bin/concrete5 c5:config set concrete.i18n.choose_language_login true

enables the language selection in the login page.

Please note that options set with c5:config take the precedence over the values set in the Concrete dashboard. So, in the example above about concrete.i18n.choose_language_login, you can't change this value in Dashboard -> System & Settings -> Basics -> Languages. If you don't want this, you can use the --generated-overrides (or -g) option (introduced in Concrete 5.7.5.4):

concrete/bin/concrete5 c5:config set -g concrete.i18n.choose_language_login true

Run Concrete jobs with c5:job

(available since Concrete 5.7.5)

Running Concrete jobs used to be done by calling specific capability URLs, for instance via cURL calls. Since version 5.7.5 you can also run jobs or job sets directly via the c5:job CLI command.

For instance, in order to run the two default jobs generate_sitemap and index_search, it's enough to write this:

concrete/bin/concrete5 c5:job generate_sitemap index_search

Starting from version 5.7.5.5 you can also run job sets in a similar way: here's how you can run the job set named Default:

concrete/bin/concrete5 c5:job --set Default

Clear the Concrete cache with c5:clear-cache

(available since Concrete 5.7.5.2)

Clearing the Concrete cache is as easy as executing this command:

concrete/bin/concrete5 c5:clear-cache

Install a Concrete package with c5:package-install

(available since Concrete 5.7.5.4)

In order to install a package you can use the c5:package-install CLI command. It's first argument is the package handle. If a package needs some install options you can pass them as further arguments. If these arguments needs to be arrays, you can append [] to the argument names.

Here's a sample session:

$ concrete/bin/concrete5 c5:package-install letsencrypt arr[]=1 arr[]=2 foo=bar bar=baz
Looking for package 'letsencrypt'... found (My Let's Encrypt).
Checking preconditions... good.
Installing package... done.

An example of installing a theme:

concrete/bin/concrete5 c5:package-install theme_package_handle --full-content-swap

Update Concrete packages with c5:package-update

(available since Concrete 5.7.5.4)

In order to update one or all package, you can use the c5:package-update command. One notable option it accepts is the --force (or its short form -f): this is very useful for package developers since it allows them to execute the upgrade process even if the package version is not changed. Another option is --all (or -a), that upgrade all the installed packages.

Note: starting from version 5.7.5.5, you can specify more than one package handle to be upgraded.

Here's a sample session

$ concrete/bin/concrete5 c5:package-update letsencrypt
Looking for package 'letsencrypt'... found (Let's Encrypt).
Checking preconditions... good.
Updating from v0.9.6 to v0.9.9... done.

$ concrete/bin/concrete5 c5:package-update letsencrypt
Looking for package 'letsencrypt'... found (My Let's Encrypt).
Checking preconditions... the package is already up-to-date (v0.9.9)

$ concrete/bin/concrete5 c5:package-update letsencrypt --force
Looking for package 'letsencrypt'... found (My Let's Encrypt).
Checking preconditions... good.
Forcing upgrade at v0.9.9... done.

Uninstall a Concrete package with c5:package-uninstall

(available since Concrete 5.7.5.)

Uninstalling a package is as simple as running a command like this:

$ concrete/bin/concrete5 c5:package-uninstall letsencrypt
Looking for package 'letsencrypt'... found (My Let's Encrypt).
Checking preconditions... good.
Uninstalling package... done.

You can also specify to move the package directory to the Concrete trash (usually located at application/files/trash) by specifying the --trash option.

Manage 5.6 and 5.7 package translations with c5:package-translate

(available since Concrete 5.7.5.4)

For a description of this command see the Localization section of the Developers manual.

Manage 5.6 and 5.7 packages with c5:package-pack

(available since Concrete 5.7.5.4)

This is a very powerful command that developers should be aware of. Here's a list of all the operations it can perform:

  • Expand short PHP open/echo tags
    You can use the --short-tags (or -s for short) option to specify that the short PHP tags <? and <?= should be expanded respectively to <?php and <?php echo. This option can have these values:
    • all (default) to expand both <? and <?= (useful for PHP versions prior to 5.4)
    • keep-echo to expand only <? but keep <?= (should be used for PHP 5.4+ where <?= is always enabled)
    • no to not expand short tags at all (should be avoided for maximum portability)

  • Create PNG icons from SVG files
    The --compile-icons option (-i for short) can be used to control if SVG files should be converted to PNG icons.
    Currently only these files can be converted:

    • <package-root>/icon.svg => <package-root>/icon.png
    • <package-root>/blocks/<block-handle>/icon.svg => <package-root>/blocks/<block-handle>/icon.png

    --compile-icons supports these values:

    • yes to always convert the SVG files to the PNG icons
    • no to never perform this operation
    • auto (default) to convert the icons only if the PNG icons don't exist or if the SVG files are newer than the PNG icons
  • Compile translation files
    (For a description of the language files see the Localization section of the Developers manual).
    The --compile-translations option (-t for short) can be used to control if the source .po translation files should be compiled to the .mo format (the one used by Concrete).
    The .po files should reside in the same directory as the .mo files (that is under <package-root>/languages/<language_code>/LC_MESSAGES).
    --compile-translations supports these values:
    • yes to always compile the .po text files to the .mo binary files
    • no to never perform this operation
    • auto (default) to compile the translation files only if the .mo files don't exist or if the .po files are newer than the .mo ones

Ok, c5:package-pack can perform the above operations. But where does it save the results? This decision is up to you:

  • you can choose to update the package directory itself (by using the --update-source-directory option or its short version -u)
  • you can choose to create a ZIP archive containing the updated files (that's very handy when you want to submit your packages to the Concrete PRB or to give your package to others), by using the --zip option (or its short version -z).
    This option accepts an optional value that specify the path of a directory where the ZIP file should be created. By default the ZIP file will be created in the directory containing the package folder.
    The name of the ZIP will be build automatically, by appending the package version to the package handle.
  • you can also use both the -u and the -z options togheter

By default, c5:package-pack automatically excludes from the ZIP files the files and the directories starting with a . (dot). The SVG icons and the .po source language files are excluded too.
If you want to keep these files in the ZIP archive, you can use the --keep option (-k for short):

  • use --keep=dot (aka -k dot) to keep the files whose name starts with a .
  • use --keep=sources (aka -k sources) to keep the SVG and .po files

  • use --keep=dot --keep=sources (aka -k sources -k sources) to keep both type of files.

    Note: in order to generate PNG icons from SVG files you'll need Inkscape installed.
    Windows users should also add Inkscape executable folder to the current PATH variable (see mlocati's My development environment for Concrete under Windows for a sample usage).

TL;DR:

  • to update the package source directory, use concrete/bin/concrete5 c5:package-pack PACKAGE_HANDLE -u
  • to create a ZIP file containing your package, use concrete/bin/concrete5 c5:package-pack PACKAGE_HANDLE -z

Executing PHP scripts with c5:exec

(available since Concrete 8.0.0)

In case you need to run a PHP script within the Concrete environment, you can use the c5:exec command.

For instance, let's assume you want to add 100 new users: you can write a create-users.php file like this:

<?php

$userRegistration = Core::make('user/registration');

for ($i = 1; $i <= 100; ++$i) {
    $userRegistration->create([
        'uName' => 'user'.$i,
        'uPassword' => 'password'.$i,
        'uEmail' => 'email'.$i.'@my.domain',
        'uIsValidated' => true,
    ]);
}

You can execute the above script executing concrete/bin/concrete5 c5:exec create-users.php from the command line.

Controlling the web server configuration with c5:service

(available since Concrete 8.0.0)

At the moment, this command is mainly meant to control the .htaccess file for the Apache web server, so that it can reflect the Pretty URL settings. Since the CLI interface is not aware of the web server that currently provides the web site, you have to specify which is your web server (currently accepted values: apache and nginx). Furthermore, the pretty urls handling needs to know which is the relative path under which your Concrete website is available, so you have to specify this path with the dir_rel.

For instance, if you want to enable pretty URLS via CLI, here's how it can be done:

First, configure Concrete:

$ concrete/bin/concrete5 c5:config set -g concrete.seo.url_rewriting true

Next, update the .htaccess file (we assume Concrete available with Apache under the webroot directory):

$ concrete/bin/concrete5 c5:service apache update dir_rel=

Checking presence of rule pretty_urls... not found. Adding it... done.
Persisting new configuration... done.

You can check if the web server configuration has been updated with the check argument:

$ concrete/bin/concrete5 c5:service apache check dir_rel=

Checking presence of rule pretty_urls... found (ok).

And here's how to remove the Pretty URL support:

$ concrete/bin/concrete5 c5:config set -g concrete.seo.url_rewriting false

$ concrete/bin/concrete5 c5:service apache update dir_rel=

Checking absence of rule pretty_urls... found. Removing it... done.
Persisting new configuration... done.

Getting information with c5:info

(available since Concrete 8.0.0)

The CLI interface can work with many Concrete instances, as well as with symlinked cores.
To check the detected environment, as well as to retrieve via command line the PHP configuration, you can run the c5:info command.

Here's a sample output:

$ concrete/bin/concrete5 c5:info

# concrete5 Version
Installed - No
Core Version - 8.0.0a4
Database Version - 20160420000000

# Paths
Web root - /var/www/mysite
Core root - /var/www/mysite/concrete

...

Upgrading Concrete with c5:update

(available since Concrete 8.0.0)

Starting from version 8, you can upgrade your Concrete version via the c5:update command line. For more details about the upgrade process see this manual page.