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?
- Install Gravity Forms and Add-Ons
- Verifying File Checksums
- Managing Forms
- Managing Entries
- Using the Built-in Help
- Advanced Usage
- Contribute on GitHub
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.
- Site migration/synchronisation: move your forms and entries to another site.
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.
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
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.
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
— — 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.
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)"
If you see an issue that needs fixing or if you’d like to submit a pull request, head over to the GitHub repository:
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.