Skip to content

CLI Installer

About this document

This guide covers installation of CiviCRM on the command-line. It assumes that you previously completed these tasks:

  1. Install a supported CMS
  2. Review the CiviCRM requirements
  3. Download the CiviCRM code. (See "Get the code" for Backdrop, WordPress or Drupal).
Limitations

At time of writing, the CLI installer is primarily tested with Backdrop, Drupal 7/8/9, and WordPress. It is primarily tested with single-site deployments. For other configurations (e.g. Joomla; e.g. multisite), it may require extra variables/options/patches.

The installer verifies requirements, prepares the database, and initializes the configuration file.

Each Civi-CMS integration has an option to install through the web interface -- which is intended for new and casual administrators.

For more advanced administrators, there is a general-purpose command-line interface (CLI) for installation. This is useful for:

  • Automating installation
  • Accessing uncommon or hidden options
  • Debugging or developing changes to the installer
Debugging and development

If you are using the CLI for debugging or development, then the CiviCRM Developer Guide has additional guidance. See Setup Reference: Overview and Setup Reference: Getting Started

Download "cv"

The CLI installer is part of cv, a general-purpose tool for managing CiviCRM on the command-line. cv is distributed in PHAR format, which is a portable executable file for PHP. It should run in most Unix-like environments that support PHP.

Simply download cv.phar and put it somewhere in the PATH. For example:

sudo curl -LsS https://download.civicrm.org/cv/cv.phar -o /usr/local/bin/cv
sudo chmod +x /usr/local/bin/cv

Change directory

To run cv, you should navigate into the base folder of the CMS. For example:

cd /var/www/example.org

Run the installer

A typical installation command will look like this:

cv core:install --cms-base-url="URL" --lang="LANG"

For example:

$ cv core:install --cms-base-url="https://example.org" --lang="fr_CA"

Found code for civicrm-core in /var/www/example.org/wp-content/plugins/civicrm/civicrm
Found code for civicrm-setup in /var/www/example.org/wp-content/plugins/civicrm/civicrm/setup
Creating file /var/www/example.org/wp-content/uploads/civicrm/civicrm.settings.php
Creating civicrm_* database tables in hydrawpcms_p7urq

There are several available options for the installer. Expand the topics below for more details.

Option: CMS Base URL
cv core:install ... --cms-base-url="https://example.org"

The "CMS Base URL" is the public URL of the website. It is required for most CLI installations.

Setting this option ensures that CiviCRM's background jobs (e.g. email-blasts and membership-reminders) can generate correct URLs.

Option: Database URL
cv core:install ... --db="mysql://user:pass@hostname:port/db"

The "Database URL" points to the MySQL database where we will install CiviCRM.

By default, CiviCRM will use the same database as the CMS. However, some administrators prefer to use a separate database. See Requirements: MySQL: Connection for more discussion.

Option: Language
cv core:install ... --lang=fr_CA

The "Language" is the primary language used by the organization.

Based on the language, the installer loads a set of default configuration data. This includes common activity types ("Meeting" or "Phone Call"), common location types ("Home" or "Office"), and so on.

Note: For a specific language to work, there must be corresponding data in the l10n folder.

Option: Sample data
cv core:install ... -m loadGenerated=1

The sample data provides a number of fake, auto-generated records -- i.e. sample contacts, contributions, activities, etc. The sample data is useful for testing or reviewing CiviCRM.

Note: At time of writing, the sample data is only supported in the default locale, en_US.

Option: Admin User (Standalone)
cv core:install ... -m extras.adminUser=USERNAME \
  -m extras.adminPass=SECRET \
  -m extras.adminEmail=ME@EXAMPLE.COM

When installing CiviCRM Standalone, you should specify the credentials for the first administrative user. If omitted, the credentials will be auto-generated and stored in the CiviCRM log.

Option: Verbose output
## Verbose
cv core:install ... -v

## Very verbose
cv core:install ... -vv

The "verbose" option provides more details about how the installer works. Enabling the verbose option helps one identify problems.

The installer may report a problem. Some common ones are:

Problem: CMS Base URL

On most systems, the --cms-base-url cannot be detected automatically. You must explicitly set it.

Problem: File write permission

The installer needs to create some files and folders. However, if the parent folder is locked-down, then you will need to relax permissions.

For example: in a Drupal site, the installer creates a file web/sites/<sitename>/civicrm.settings.php. You may need to mark the parent folder (web/sites/default or web/sites/example.org) as writeable, e.g.:

## Grant write-access for the owner-user
chmod 755 web/sites/default

## Grant write-access for all users
chmod 777 web/sites/default
Problem: PHP or MySQL configuration

The PHP or MySQL configuration may require an update - e.g. to expand the PHP memory limit, to enable a PHP extension, or to enlarge a MySQL buffer. Common issues are discussed in the Requirements.

Error: Call to undefined method Drupal::entityManager

This error appears installing with the --user option under Drupal 9. Avoid this error simply by not using the --user option.

For common problems, you can simply fix the problem and re-run the installer.

For unusual problems, be sure to enable verbose output (-v or -vv). It may also help to inspect the model, plugins, or requirements.

Configure the site

After running core:install, you can login to the CMS, open CiviCRM, and configure additional details. The System Administrator Guide has more advice on how to configure CiviCRM.

If you are automating the installation, then you may wish to automate some common configuration steps, such as:

Task: Manage extensions

To view available extensions:

cv ext:list

To download extensions from the Extension Directory:

cv dl EXTENSION_1 EXTENSION_2 ...

By default, it downloads stable releases. To download pre-releases (alphas/betas), use dev feed or an explicit URL:

## Download from the "dev" feed
cv dl --dev EXTENSION_1 EXTENSION_2 ...

## Download from an explicit URL
cv dl EXTESION_KEY@ZIP_URL

Alternatively, if you downloaded an extension by other means, then you may enable it:

cv en EXTENSION_1 EXTENSION_2 ...
Task: Manage settings

Many options are managed through the Settings framework. These may be configured in the CLI:

## List current settings
cv api setting.get

## Update specific settings
cv api setting.create KEY_1=VALUE_1 KEY_2=VALUE_2 ...
Task: Clear caches
cv flush