Update 27 February 2020: Added command to delete all entries for a form (see Advanced usage)
Update 6 June 2016: added contribution section.
——–
The Gravity Forms CLI Add-On was released last week. What is it? What can it do? And how on earth do you use it?
- Introduction
- Requirements
- Installation
- Install Gravity Forms and Add-Ons
- Verifying File Checksums
- Managing Forms
- Managing Entries
- Using the Built-in Help
- Advanced Usage
- Contribute on GitHub
- Conclusion
Introduction
The Gravity Forms CLI Add-On provides a Command Line Interface (CLI) for any Gravity Forms installation. This means that you don’t need a browser to interact with Gravity Forms and manage forms and entries, you can do it from the command line in a terminal window (Command Prompt in Windows).
There are also some cool features in the CLI that are currently not available by the Gravity Forms core plugin, for instance, entry duplication, JSON entry import & export, and file checksum verification.
What’s the Gravity Forms CLI for?
Here are some use cases made possible by the Gravity Forms CLI:
- Better security: verify that the Gravity Forms plugin files haven’t been tampered with.
- Easier Continuous Integration (e.g. on Travis CI, Codeship etc): download, install and activate Gravity Forms and then populate with sample forms and entries for use in unit and integration tests.
- Volume testing: duplicate some entries a few hundred thousand times to test how your site will scale.
- Faster Site maintenance: instantly create, edit, export, import and duplicate forms and entries.
- Mitigate plugin conflicts: No JavaScript errors caused by other plugins loading their scripts where they shouldn’t.
- Site migration/synchronisation: move your forms and entries to another site.
Requirements
The Gravity Forms CLI requires the WP-CLI and command line access to your WordPress installation. You may need to ask your host if you can install the WP-CLI – it’s not a WordPress plugin or a feature that you can just download and activate. It’s the WP-CLI that enables your commands to be routed to Gravity Forms.
Installation
The Gravity Forms CLI Add-On is publicly available on the WordPress plugins repository so you can download it from the WordPress plugins page in your site’s dashboard. You can also download the zip file from the repository and install it manually:
Of course, you can also install it using the WP-CLI. The following command will download, install the Gravity Forms CLI Add-On directly from the repository and activate it immediately.
wp plugin install gravityformscli --activate
Install Gravity Forms
After installing the Gravity Forms CLI Add-On, if you don’t already have Gravity Forms installed you can install it via the CLI. The following command will download Gravity Forms and activate it. You’ll need to replace the key with your valid license key.
wp gf install --key=xxxxxx --activate
You can also install any of the Gravity Forms Add-Ons by passing the add-on’s slug. For example, the following command will install the Polls Add-On
wp gf install gravityformspolls --key=xxxxxx
Verify the Gravity Forms File Checksums
Once you’ve got Gravity Forms installed you may want to double check that the files have not be tampered with at all. Even if you’ve had Gravity Forms installed for a while, you may want to double check that no malware has found its way into the plugin files since it was last updated. This is especially useful for server administrators who need a quick way to verify the integrity of all the sites on their servers.
The following command will download the file checksums for the version you have installed and compare them against all the files in the plugin folder.
wp gf tool verify-checksums
If the checksum verification fails then there’s a problem with your Gravity Forms plugin files and you should delete the whole folder and reinstall.
Managing Forms
The Gravity Forms CLI allows you list, view, create, edit, export, import and duplicate forms. The following command will display the form list along with the entry and view counts.
wp gf form list
The form create subcommand will create a form.
wp gf form create "Support Form"
usage: wp gf form create [<title>] [<description>] [--form-json=<form-json>] [--porcelain]
Once you’ve created a form you can add fields to it using the field create subcommand.
wp gf field create text "Name"
usage: wp gf field create <form-id> [<type>] [<label>] [--field-json=<field-json>]
You can even edit the field JSON configuration right in the terminal with the wp gf field edit command.
Here’s a short video (41 seconds) demonstrating some of the form management features.
Managing Entries
You can also use the CLI to list, view, create, edit, export, import and duplicate entries.
The following command will display the entry list.
wp gf entry list 23
usage: wp gf entry list <form-id> [--status=<status>] [--format=<format>] [--page_size=<page_size>] [--offset=<offset>]
Entries can be viewed by using the entry get subcommand as follows:
wp gf entry get 282
usage: wp gf entry get <entry-id> [--format=<format>] [--raw]
Note that the raw switch will return the entire entry object which is useful if you need the entire entry object in JSON format.
Duplicating entries can be really useful when you need to perform volume testing or if you need to populate sample data for a demo. The “entry duplicate” subcommand will duplicate an entry as many times as you like.
wp gf entry duplicate 275
usage: wp gf entry duplicate <entry-id> [--count=<count>]
You can also create new entries from the command line using the wp gf entry create subcommand. The following command will create a a new entry for the “Support Form” we created above which current has only one field.
wp gf entry create 25 --field_1=Steve
usage: wp gf entry create [<entry-json>] [<form-id>] [--<field>=<value>]
Deleting entries works the same way as the browser-based UI. Delete it once and it’s trashed, delete it again and it’s deleted permanently.
wp gf entry delete 277
usage: wp gf entry delete <entry-id>... [--force]
The –force flag will force the entry to be deleted permanently instead of being moved to the trash.
You can specify multiple entry IDs by separating them with spaces.
wp gf entry delete 279 280 281
Entry Export & Import
The core Gravity Forms plugin currently supports entry export in CSV format only and importing entries is not currently supported. The generated file is useful for creating human readable reports but you’ll need GravityView’s Gravity Forms Entry Importer to import the entry data.
The wp gf entry export command allows you to export entries in both CSV and JSON formats. The default format is CSV so we need to specify the JSON format like this:
wp gf entry export 23 --format=json
You can then use the wp gf entry import command to import the entries on the same or different site.
wp gf entry import file-name.json
The following 37 second video demonstrates the main commands available for entry management
Using the Built-in Help
You don’t need to bookmark this post. Any time you need to check the available commands or their usage you can use the built-in usage help. For example:
wp help gf
wp help gf form
wp help gf form list
Advanced Usage
— — porcelain
The commands above have focused on command line usage so the response from the CLI has always been a friendly message. However, the friendly message is not much use if we need to use the response as the input for a new command or for another process that will read the output of a script. This is where the porcelain flag comes in. The porcelain flag will ensure that the output contains purely the output of the command without any friendly messages.
For example:
wp gf form create "Support Form" --porcelain
— — format=<format>
By default, the output format for the list commands is “table”. However, sometimes we need the command to output the list in a different format so we can reuse it in another command or process. The following options are available: table, json, ids, csv, count
Using the output in another command
Now we know how to the output in a useful format, we can combine two Gravity Forms CLI commands by using the output of one command as the input of another. This is achieved by the standard [command] $([command]) notation.
For example, the following command will empty the trash for form 25:
wp gf entry delete $(wp gf entry list 25 --status=trash --format=ids)
(Note: You may find you need to use the page_size argument to return all the entries)
The following example duplicates entry 276 by using the raw JSON output from the entry get command as the input for the wp gf entry create command:
wp gf entry create "$(wp gf entry get 276 --raw --format=json)"
Delete all entries for a form
1 is the form ID
wp gf entry delete $(wp gf entry list 1 --format=ids ) --force
Contribute
If you see an issue that needs fixing or if you’d like to submit a pull request, head over to the GitHub repository:
Conclusion
The Gravity Forms CLI gives system administrators and developers powerful tools they need to manage Gravity Forms installations from bash scripts and without leaving the command line. It’s a very fast way to manage forms and entries and it allows advanced users to achieve things that are currently not possible with the Gravity Forms core plugin.
If you’ve found the Gravity Forms CLI useful, I’d love to hear from you. Please leave a comment describing how you’ve used it.
Glenn Bastiaansen says
February 16, 2017 at 9:02 amHi,
I tried to use this and it worked fine, but when i tried to install it in a bash script for wpcli& gfcli it was not. When i used the form create command i got an error. It could not insert the form into the table because it did not excist. The error looked like this: “WordPress databaserror: [Table DATABASENAME.prefix_rg_lead doesn’t exist”. So my thought was that there were no databse tables for Gravity Forms. I looked in my PHPMyAdmin and there were no tables. They were only created when i logged-into my WP-admin. So i created a PHP file before my create form command.
I used it like this:
wp gf install –key=xxxxx –activate
wp gf tool verify-checksums
chmod +rx gravity_forms_setup.php
php gravity_forms_setup.php
wp gf form create “Contact”
And gravity_forms_setup.php is like this:
require_once(“wp-load.php”);
require_once (“./wp-content/plugins/gravityforms/gravityforms.php”);
$setup = new GFForms();
$setup->setup(true);
When you give true as parameter it wil create the tables. Maybe are there more people with this error and i hope i helped them out.
Glenn
Rochel says
July 27, 2018 at 8:12 amI’m totally new to this whole WP-CLI thing but I downloaded Putty, and managed to install Wp-Cli with the wget command. I couldn’t get the ‘sudo mv wp-cli.phar /usr/local/bin/wp’ to work right so that I could use ‘wp’ commands. I’m sure I’m doing something really dumb, but I’m totally at a loss. I ended up creating a wp folder via my ftp and moving the wp-cli.phar file into it but I’m sure that didn’t help my cause cuz’ it’s still not letting me use wp before the commands. Any guidance would be hugely appreciated!
T4ng says
February 27, 2020 at 4:10 pmBasic question: how to remove ALL GF entries in one single command?
Steven Henty says
February 27, 2020 at 4:34 pmTry this (1 is the form ID): wp gf entry delete $(wp gf entry list 1 –format=ids ) –force
Matt says
June 5, 2020 at 3:22 amHi Steven,
Thanks for the great tutorial. It cleared some things up for me that I couldn’t get from the documentation. Just wondering if there is any way to bulk update entries that meet a certain criteria?
In my app I have a form (ID-7) with a select field that can be any of “Active”, “Review” or “Disabled”. I’m wanting to update all entries with “Active” in this field to “Review”. Below is a bash script that gets me close, but this applies to all records (or just the first 20 if page_size isn’t specified). Do you know how this could be achieved?
for ID in $(wp gf entry list 7 –format=ids); do wp gf entry update $ID –field_37=”Review”; done
Thanks