The new and improved cli.php: now a new way to interact with api v3

2011-10-31 07:45
Written by

As of the Bourne, UK sprints last August, bin/cli.php has been completely re-written for 4.1.

If you are an integrator or user, you might not have noticed this file. It used to be a PHP class that was used by many of the individual scripts in the bin directory.

Now, it's a command line program designed to be run directly.

With cli.php you can run any function defined in the API version 3.

If you run the script without any arguments, you'll get a usage statement explaining how it works:

0 jamie@chicken:bin$ php cli.php
The --action argument is required
Usage: cli.php -e entity -a action [-u user] [-s site] [--output] [PARAMS]
 entity is the name of the entity, e.g. Contact, Event, etc.
 action is the name of the action e.g. Get, Create, etc.
 user is an optional username to run the script as
 site is the domain name of the web site (for Drupal multi site installs)
 --output will print the result from the api call
 PARAMS is one or more --param=value combinations to pass to the api

0 jamie@chicken:bin$

Anyone who has tried to run a script in the bin directory in the past will notice two important things:

  1. There is no longer any need to pass a UF username and password or CiviCRM site key. That means no juggling of passwords or looking up crazy long strings in your civicrm.settings.php file. After discussing the security implications, we decided that anyone with command line access and read-access to your civicrm.settings.php file already has full access to your database, so these requirements are simply an added burden without providing additional security. By default, the script will run as the anonymous user, so you still may want to optionally pass a UF username if you are running functions that will check permissions before executing.
  2. --site allows you to specify the domain name of the site you are operating on (mostly relevant if you are running in a Drupal multi site environment). Previously some scripts provided this option - now it's available for all api functions in a consistent way.

We're in the process of adding all functionality found in bin scripts to the API and removing them from the bin directory. Also, stay tuned for news on Consolidated Cron Make it Happen

Filed under