civicrm / cv
CLI tool for CiviCRM
Installs: 15 328
Dependents: 0
Suggesters: 0
Security: 0
Stars: 29
Watchers: 17
Forks: 30
Open Issues: 34
Requires
- php: >=7.3.0
- ext-json: *
- cweagans/composer-patches: ~1.0
- lesser-evil/shell-verbosity-is-evil: ~1.0
- psr/log: ~1.1 || ~2.0 || ~3.0
- psy/psysh: @stable
- stecman/symfony-console-completion: ^0.11.0
- symfony/console: ~5.4
- symfony/process: ~5.4
Replaces
- civicrm/cv-lib: v0.3.59
- dev-master
- v0.3.59
- v0.3.58
- v0.3.57
- v0.3.56
- v0.3.55
- v0.3.54
- v0.3.53
- v0.3.52
- v0.3.51
- v0.3.50
- v0.3.49
- v0.3.48
- v0.3.47
- v0.3.46
- v0.3.45
- v0.3.44
- v0.3.43
- v0.3.42
- v0.3.41
- v0.3.40
- v0.3.39
- v0.3.38
- v0.3.37
- v0.3.36
- v0.3.35
- v0.3.34
- v0.3.33
- v0.3.32
- v0.3.31
- v0.3.30
- v0.3.29
- v0.3.28
- v0.3.27
- v0.3.26
- v0.3.25
- v0.3.24
- v0.3.23
- v0.3.22
- v0.3.21
- v0.3.20
- v0.3.19
- v0.3.18
- v0.3.17
- v0.3.16
- v0.3.15
- v0.3.14
- v0.3.13
- v0.3.12
- v0.3.11
- v0.3.10
- v0.3.9
- v0.3.8
- v0.3.7
- v0.3.6
- v0.3.5
- v0.3.4
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.22
- v0.2.21
- v0.2.20
- v0.2.19
- v0.2.18
- v0.2.17
- v0.2.16
- v0.2.15
- v0.2.14
- v0.2.13
- v0.2.12
- v0.2.11
- v0.2.10
- v0.2.9
- v0.2.8
- v0.2.7
- v0.2.6
- v0.2.5
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.32
- v0.1.31
- v0.1.30
- v0.1.29
- v0.1.28
- v0.1.27
- v0.1.26
- v0.1.25
- v0.1.24
- v0.1.23
- v0.1.22
- v0.1.21
- v0.1.20
- v0.1.19
- v0.1.18
- v0.1.17
- v0.1.16
- v0.1.15
- v0.1.14
- v0.1.13
- v0.1.12
- v0.1.11
- v0.1.10
- v0.1.9
- v0.1.8
- v0.1.7
- v0.1.6
- v0.1.5
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-colemanw-patch-1
This package is auto-updated.
Last update: 2024-12-20 19:30:18 UTC
README
The cv
command is a utility for interacting with a CiviCRM installation. It performs an automatic scan to locate and boot the CiviCRM installation. It provides command-line access to helper functions and configuration data, such as APIv3 and site URLs.
Requirements
- PHP v7.3+.
- A local CiviCRM installation.
- Systems with special file-layouts may need to configure bootstrap.
Download
cv
is distributed in PHAR format, which is a portable executable file (for PHP). It should run on most Unix-like systems where PHP is installed.
Here are three quick ways to download it:
-
Download the latest release of
cv.phar
(SHA256, GPG) and put it 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
(Learn more: Install
cv.phar
as system-wide tool (Linux/BSD/macOS)) -
Or... add
cv
and other CiviCRM tools to a composer project (Drupal 9/10/11)composer require civicrm/cli-tools
(Learn more: Install
cv.phar
as project tool (composer)) -
Or... use phar.io's
phive
installer to download, validate, and cache thecv.phar
file.phive install civicrm/cv
(Learn more: Install
cv.phar
as project tool (phive))
There are several more options for downloading cv
. See also:
- Download URLs for alternate versions
- Comparison of install options
- Install
cv
as a system-wide/standalone tool - Install
cv
as a tool within another project
Documentation
cv
provides a number of subcommands. To see a list, run cv
without any arguments.
For detailed help about a specific subcommand, use -h
as in cv api -h
.
There are some general conventions:
- Many subcommands support common bootstrap options, such as
--user
,--level
, and--test
. - Many subcommands support multiple output formats using
--out
. You may set a general preference with an environment variable, e.g.export CV_OUTPUT=json-pretty
orexport CV_OUTPUT=php
.
Example: CLI
me@localhost$ cd /var/www/my/web/site ## Clear caches me@localhost$ cv flush ## Manage extensions me@localhost$ cv ext -Li me@localhost$ cv dl cividiscount me@localhost$ cv en cividiscount me@localhost$ cv dis cividiscount me@localhost$ cv path -x cividiscount me@localhost$ cv url -x cividiscount ## Manage settings me@localhost$ cv vget me@localhost$ cv vget /mail/ me@localhost$ cv vset mailerBatchLimit=100 ## Call APIs me@localhost$ cv api3 contact.get last_name=Smith me@localhost$ cv api4 Contact.get +w last_name=Smith ## Improvise PHP me@localhost$ cv ev 'echo Civi::paths()->getPath("[civicrm.root]/.");' me@localhost$ cv scr /path/to/my-script.php me@localhost$ cv cli ## Improvise web requests me@localhost$ cv url civicrm/dashboard --open me@localhost$ cv url civicrm/dashboard --open -LU admin me@localhost$ cv http civicrm/dashboard me@localhost$ cv http civicrm/dashboard -LU admin ## Inspect events and services me@localhost$ cv event me@localhost$ cv event /flexmailer/ me@localhost$ cv service me@localhost$ cv service /flexmailer/
If you intend to run unit-tests, and if you do not use civibuild
,
then you may need to supply some additional site information (such as
the name of the test users). To do this, run:
me@localhost$ cd /var/www/my/web/site me@localhost$ cv vars:show me@localhost$ cv vars:fill me@localhost$ vi ~/.cv.json me@localhost$ cv vars:show
Example: PHP
Suppose you have a standalone script or a test runner which needs to execute
in the context of a CiviCRM site. You don't want to hardcode it to a
specific path, create special-purpose config files, or require a specific
directory structure. Instead, call cv php:boot
and eval()
. The simplest way:
eval(`cv php:boot`)
However, it is better to create a small wrapper function to improve error-handling and output parsing:
/** * Call the "cv" command. * * @param string $cmd * The rest of the command to send. * @param string $decode * Ex: 'json' or 'phpcode'. * @return string * Response output (if the command executed normally). * @throws \RuntimeException * If the command terminates abnormally. */ function cv($cmd, $decode = 'json') { $cmd = 'cv ' . $cmd; $descriptorSpec = array(0 => array("pipe", "r"), 1 => array("pipe", "w"), 2 => STDERR); $env = (!empty($_ENV) ? $_ENV : getenv()) + array('CV_OUTPUT' => 'json'); $process = proc_open($cmd, $descriptorSpec, $pipes, __DIR__, $env); fclose($pipes[0]); $result = stream_get_contents($pipes[1]); fclose($pipes[1]); if (proc_close($process) !== 0) { throw new RuntimeException("Command failed ($cmd):\n$result"); } switch ($decode) { case 'raw': return $result; case 'phpcode': // If the last output is /*PHPCODE*/, then we managed to complete execution. if (substr(trim($result), 0, 12) !== "/*BEGINPHP*/" || substr(trim($result), -10) !== "/*ENDPHP*/") { throw new \RuntimeException("Command failed ($cmd):\n$result"); } return $result; case 'json': return json_decode($result, 1); default: throw new RuntimeException("Bad decoder format ($decode)"); } } eval(cv('php:boot', 'phpcode')); $config = cv('vars:show'); printf("We should navigate to the dashboard: %s\n\n", cv('url civicrm/dashboard'));
Example: NodeJS
See https://github.com/civicrm/cv-nodejs
Bootstrap
cv
must find and bootstrap the local instance of CiviCRM, Drupal, WordPress, or similar. This may work a few ways:
-
Automatic: By default,
cv
checks the current directory and each parent directory for evidence of well-known environment (such as Drupal or WordPress).The automatic search is designed to work with a default site-layout -- as seen in a typical "zip" or "tar" file from
drupal.org
,wordpress.org
, or similar. Some deployments add more advanced options -- such as configuring "multi-site", adding bespoke "symlinks", or moving thewp-admin
folder. For advanced layouts, you may need to set an environment variable. -
CIVICRM_BOOT
(new protocol): Boot the CMS first (and then ask it to boot CiviCRM). This is more representative of a typical HTTP page-view, and it is compatible with commands likecore:install
. Set this environment variable to specify the CMS type and base-directory. Compare:export CIVICRM_BOOT="Drupal://var/www/public" export CIVICRM_BOOT="Drupal8://admin@/var/www/public" export CIVICRM_BOOT="WordPress:/$HOME/sites/my-wp-site/web/" export CIVICRM_BOOT="Auto://."
-
CIVICRM_SETTINGS
(old protocol): Boot CiviCRM first (and then ask it to boot the CMS). Set this environment variable to specify thecivicrm.settings.php
location. Compare:export CIVICRM_SETTINGS="/var/www/sites/default/files/civicrm.settings.php" export CIVICRM_SETTINGS="Auto"
(Note: In the legacy protocol,
cv
loads CiviCRM and then asks CiviCRM to boostrap the CMS. However, it is less representative of a typical HTTP page-view, and it is incompatible with commands likecore:install
. You might use it for headless testing or as fallback/work-around if any bugs are discovered in the standard protocol.)
NOTE: In absence of a configuration variable, the Automatic mode will behave like
CIVICRM_SETTINGS="Auto"
(in v0.3.x). This is tentatively planned to change in v0.4.x, where it will behave likeCIVICRM_BOOT="Auto://."
Additionally, some deployments handle multiple sites ("multisite"/"multidomain"). You should target a specific site using --hostname
or HTTP_HOST
.
Here are a few examples of putting these together:
## Use --hostname for a domain export CIVICRM_BOOT="WordPress:/$HOME/public_html/" cv --hostname='www.example.org' ext:list -L
## Use HTTP_HOST for a domain export CIVICRM_BOOT="WordPress:/$HOME/public_html/" export HTTP_HOST=www.example.org cv ext:list -L
## Use --hostname for a subfolder export CIVICRM_BOOT="WordPress:/$HOME/public_html/" cv --hostname='www.example.org/nyc' ext:list -L
Autocomplete
There is limited/experimental support for shell autocompletion based on stecman/symfony-console-completion. To enable it:
# BASH ~4.x, ZSH source <(cv _completion --generate-hook) # BASH ~3.x, ZSH cv _completion --generate-hook | source /dev/stdin # BASH (any version) eval $(cv _completion --generate-hook)
Development
For more information, see doc/develop.md.