How to list and search WordPress users with WP CLI

WP CLI is a powerful command line tool that allows you to manage all things WordPress. There is a variety of different WP CLI commands that are available, such as installing WordPress core and plugin updates, moderating comments, reading and updating site options, and many more. Using WP CLI can be often much faster than using the standard WordPress dashboard. Moreover, some of the WP CLI features are not available out of the box from the WordPress admin.

In this article, we are going to focus on listing and searching WordPress user data with WP CLI. This includes both standard user registration data and custom user meta data. Since the user meta data is not available in the WordPress dashboard by default, by using the WP CLI tool you will be able to easily load and search your custom user meta fields.

 

Getting started

In order to follow this tutorial, you need the following:

• WordPress installation with a bunch of registered users – we recommend practicing on a localhost (non-production) installation if you are new to WP CLI
• A terminal application
• WP CLI – you can follow these instructions to install WP CLI

Once you have these in place, open your terminal app and let’s get started.

Listing WordPress users with WP CLI

The most simple way to list WordPress users is by using the wp user list command:

$ wp user list

This will list the users with their main data: ID, username, name, email, date registered and roles. Date registered is one of the fields that is not available in the WordPress dashboard.

Sorting the user list

As you can see from the example above, the user list is by default sorted by their usernames. You can change  the default sorting order by using the –orderby and –order options. With the –orderby option you can set the name of the field to order by, for example user_email. With the –order option you can set whether to sort the list in a ascending or descending order, by using the asc and desc values respectively.

For example, you can sort the user list to show the most recently registered users first, by using the following command:

$ wp user list --orderby=user_registered --order=desc

And the output would be:

Loading only specific fields

If you would like to set which fields to be loaded, you can use the –fields options. You can specify one or more fields to load, by separating the field names with commas. All of the available fields are listed in this guide.

For example, if we want to load only the user ID, email and nice name, we could use the following command:

$ wp user list --fields=ID,user_email,user_nicename

Which would give us the following result:

If you want to go one step further and combine it with the previous example, you could sort this list by the user IDs:

$ wp user list --fields=ID,user_email,user_nicename --orderby=ID

Filtering users by role

Another option that the wp user list command gives us, is filtering by role. You can do this by using the –role option. When using this option, you need to set the ID of the role that you are filtering by, and not its name. For example, if you use bbPress you will have users whose role is Participant. The ID of this role is bbp_participant, so this is the value that you need to use in the –role filter.

Let’s see a few examples. We’ll start with the most simple one, which is just filtering the users by a single role – in this example we’ll list all the users who are subscribers:

$ wp user list --role=subscriber

which would give us:

The –role option also allow us to filter the users by multiple roles. You can specify more than one role, by using commas as a delimiter. When filtering by multiple roles, the result would be all the users who have all of the roles assigned.

For example, if we use the following filter:

$ wp user list --role=subscriber,bbp_participant

we would get all the users who are both subscribers and participants (but not the ones who have only one of these roles assigned).

 

Searching WordPress users with WP CLI

WP CLI doesn’t provide an out of the box option to search users, however we can use the grep command to do that. The grep command is available on Linux, Apple OS X and Unix-like operating systems. This command is not available on Windows, so if you are using Windows you should be able to accomplish similar results with the findstr command.

The grep command searches for a string in a defined text. When combined with the pipe command, grep will search the result of a command and it would return only the items that match the search string.

For example, if we want to find the users whose name is Olivia we could use the following command:

$ wp user list | grep Olivia

Basically what this command does, is first load all the users with the wp list command. Then it filters the result to only show the lines that contain the “Olivia” string.

Unfortunately, as you can see, with this command the results are not nicely formatted, but it’s still readable enough.

Since the grep command would search the entire line, it might also show you users whose username or email contains “Olivia”, but their name doesn’t. If you want to make sure that the search matches a specific field only, the best way to do that is by limiting the fields in the result:

$ wp user list --fields=ID,display_name,user_registered | grep Olivia

In this example, we load only the ID, name and date registered fields, so do not load other fields that could possibly contain the search string.

It’s also important to mention that if you search string contains empty spaces, you would need to wrap the search text in quotes:

$ wp user list | grep "Olivia Murray"

Also, please keep in mind that grep performs a case sensitive search, so with the examples above, it would return all the lines that contain “Olivia”, but not the ones that contain “olivia”. To perform a case insensitive search, just add the -i parameter:

$ wp user list | grep -i Olivia

Listing user meta

Besides the default user fields, you can also load user meta fields with the wp user list command. You can do this by using the –meta_key option and specify the key of the meta field. Using this option by itself won’t list the meta field data, so you would also need to use the –fields option to load the field in the list.

Let’s say that we have a user meta field that stores the users’ occupations and that the meta key of this field is “occupation”. To load this field in the list, we can use the following command:

$ wp user list --fields=ID,user_login,occupation --meta_key=occupation

With this command we’ll get the following result:

It’s important to mention that this command will list only the users who have some data stored in the selected meta field.

Similarly to the examples above, you can use the grep command to search the user meta. For example, if you want to find all the users whose occupation is somehow related with marketing, you can use the following command:

$ wp user list --fields=ID,display_name,occupation --meta_key=occupation | grep -i marketing

Exporting the user data with WP CLI

You can export the user data by using the output redirection command (>). With this command you can save the result from a command into a file.

When performing the export, you can also choose the format of the data. The wp user list command provides a –format option that allows you to specify the format of the data. The default format is table, but you can also choose between csv, json and yaml.

The following example creates a CSV file called export.csv that contains the results from the wp user list command:

$ wp user list --format=csv > export.csv

The file will be created where your current terminal working directory is (most likely your WordPress root folder). You can also specify a full path if you would like the file to be placed somewhere else.

Here is how the file will look like:

Performing more advanced user searches and exports

As you can see, you can use the WP CLI tool to perform more advanced user actions, that are not available in the WordPress dashboard by default. However, this tool also has its limitations – for example, you can’t load more than one user meta field or you can’t perform arithmetic operations (such as is greater or smaller) on these fields.

If you need to apply more advanced WordPress user filters and searches, you can use the Users Insights plugin that comes with a smart filters feature. The smart filters provide you different operators based on the type of the fields. They can also be stacked together, so you can perform multiple searches at once.

The smart filters support the default WordPress user data, user meta fields and also various third party integrations. The results from the filters can be also easily exported.