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

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.

: 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.

(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.

: 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.

: 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.

: 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:

https://wordpress.org/plugins/gravityformscli/

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

Gravity Forms CLI: Verify File 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

Gravity Forms CLI: the 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]

Gravity Forms CLI: create a form

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>]

Gravity Forms CLI: create a field and add it to the form.

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>]

Gravity Forms CLI: the entry list

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>]

Gravity Forms CLI: duplicate entries

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>]

Gravity Forms CLI: wp gf entry create

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]

Gravity Forms CLI: wp gf entry delete

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

Gravity Forms CLI: wp gf entry delete multiple

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

Gravity Forms CLI: wp help gf

wp help gf form

Gravity Forms CLI: wp help gf form

wp help gf form list

Gravity Forms CLI: 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

Gravity Forms CLI: wp gf form create 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

Gravity Forms CLI: wp gf entry list format

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)

Gravity Forms CLI: use output of one CLI command as input for another

(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)"

Gravity Forms CLI: using the output of the entry get command in entry create

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:

https://github.com/gravityforms/gravityformscli

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.