Common WP-CLI Commands to Master: wp term

WP-CLI is the command-line interface for WordPress and an alternative to the WordPress admin. It allows performing much more complex maintenance operations for your site, from updating plugins and configuring multisite installs, to deleting revisions, regenerating thumbnails or doing search replaces in the database the safe way.

WP-CLI is a powerful tool to master. So we decided to put together a series of WP-CLI tutorials with helpful commands you can use to manage your website. We won’t include here WordPress core operations as these are usually handled by your host; thus, we’re going to focus on day-to-day maintaining operations for site improvements.

Plenty of tutorials teach you how to install WP-CLI and some of the more basic commands, but we won’t get into that. This series of articles aims to gather up common use cases for WP-CLI, beyond the simple plugin updates or regenerating thumbnails. It’s a series of useful how-to’s, combining both WP-CLI and bash commands.

For example, it’s easy to delete or add a new tag or category, but what if you need more specific operations like deleting the less popular tags? This is a more specific task you might run into, and you won’t find this answer in the WordPress codex.

We’ll take the most used WP-CLi commands one by one and we’ll start with wp term.

The terms in WordPress are the items in a taxonomy. Categories and tags are the two default taxonomies that come with every new WordPress install. They help you sort out the content on your site, making it easy for your readers to navigate your site and find what they are searching for. Categories usually describe broad topics of your site, whereas tags describe specific details of your posts.

All is good until you start refurbishing your site and you want to change, update or delete these categories and tags and you happen to have a site that has hundreds of thousands of articles. In this case, the easy and secure way to update them is through WP-CLI.

Here are the wp term commands you can use:

wp term create	
wp term delete	
wp term generate	
wp term get	
wp term list	
wp term meta	
wp term recount	
wp term update

wp term meta add	
wp term meta delete
wp term meta get	
wp term meta list
wp term meta patch
wp term meta pluck	
wp term meta update

For example, if you want to list all categories:

wp term list category

Or you want to update a category’s name:

wp term update category 1 --name=Blog

#Remove “Uncategorized” from Posts with More than One Category

“Uncategorized” is the default category in WordPress, so it’s pretty common that it remains forgotten in some older posts. Keeping this category does not help your users find what they are searching for and it makes your site look sloppy and unprofessional. Needless to say, you shouldn’t have posts in this category. You can rename it or remove it, but the first thing you should do is to make sure it doesn’t appear in posts that already have a category assigned.

You can create a bash script with the following code and then run it:

#!/bin/bash 
for post in $(wp post list --field=ID) 
do 	
count=$(wp post term list $post 'category' --fields='name' --format="count") 
if [ "$count" -gt "1" ] 
then wp post term remove $post category 'uncategorized' 
fi 
done

Or you can simply run the command in your terminal:

for post in $(wp post list --field=ID); do count=$(wp post term list $post 'category' --fields='name' --format="count"); if [ "$count" -gt "1" ]; then wp post term remove $post category 'uncategorized'; fi; done

You can choose whichever method you are more comfortable with. If your WP-CLI command is complex, then you’ll have a better overview over it if you write it into a bash script.

#Remove Tags that Appear in Less than 100 Posts

There are many ways you can combine WP-CLI commands with bash commands to get the desired result. For example, here are two ways to remove the tags that appear in less than 100 posts:

for x in $(wp term list post_tag --format=ids) ; do count_posts=$(wp term list post_tag --term_id=$x --field=count); if [ $count_posts -lt 3 ]; then wp term delete post_tag $x; fi; done

for x in $(wp term list post_tag --format=ids) ; do count_posts=$(wp rest post list --tags=$x | wc -l | awk '{print $1-1}'); if [ $count_posts -lt 100 ]; then wp term delete post_tag $x; fi; done

With WP-CLI, there isn’t a one-way method to resolve a certain task, you just have to know the available commands, know a little bash scripting and use your imagination.

#Create a File List

Sometimes you need to create a file with all the tags that you want to remove. Maybe you want to pass it to your developer to remove them or you want to manually edit the tags that you want to erase or to keep. In any case, here’s how you can create a text file with all your tags IDs:

wp term list post_tag --format=ids > all_tags.txt

You can also generate a .CSV file, which will make it easier to manually remove the tags, as you will have all the fields of the tag, instead of only the ID:

wp term list post_tag --format=csv > all_tags.csv 

#Remove Tags from a File List, Based on Slug

Supposing you have a file (tags_list.txt) that contains a list of tag slugs, here is how you can remove the tags that have the respective slugs:

for x in $(cat www/wp-content/uploads/tags_list.txt) ; do wp term delete post_tag $x --by=slug ; done

Similarly, you can remove the tags from a file list based on ID, but if you manually need to edit the tags list, slugs are more descriptive than IDs and allow you to make sure you don’t delete a tag you still want to use.

#Add a New Category to a List of Posts in a File List

If you want to add a new category to more than a few posts, you can create a list with all the posts IDs, then run:

for x in $(cat www/wp-content/uploads/post_list.txt) ; do wp post term add $x category code ; done

You don’t need to create the new category beforehand, it will be automatically created when you add it to the posts.

#Remove All Post Tags, Except a Given List in a .CSV Format

Let’s assume you’ve created a .CSV file with all the IDs of the tags you want to keep. To remove all tags except the ones from this list, run:

wp term list post_tag --exclude=$(cat exclude_tags.csv) --field=term_id | xargs wp term delete post_tag

This will send the output of wp term list command to xargs, which will execute the wp term delete command for each post tag that is not in the list.

#Remove a List of Terms from a List of Posts

If you want to remove some tags/ categories, but you don’t want to remove them from all of your posts, only from some of them, you can create two text files:

1. one that contains a list of tags/ categories slugs that you want to remove
2. one that contains the post IDs of the posts from where you want to remove the tags.

Then you can run:

for x in $(cat www/wp-content/uploads/posts_list.txt) ; do wp post term remove $x post_tag $(cat www/wp-content/uploads/tags_to_remove.txt) ; done

This command removes the post tags, but you can similarly remove categories. A post can have one or more of the tags in the list, the command will remove the tags from each post that it can find.

#Restore a deleted tag

In case you want to restore a deleted tag, you need to have a list of all the posts that had that tag. To do this, you can import a database backup on your development site (at Presslabs we offer free development sites) or your local site, then using WP-CLI, extract the post IDs that had that tag into a file:

wp post list --tag_id=10495 --field=ID > post_ids.txt

Copy the file with the post IDs into into the uploads folder of the live site. Then recreate the tag and copy the new tag ID:

wp term create post_tag the_lost_and_found

Finally, add it to the corresponding posts:

for x in $(cat www/wp-content/uploads/post_ids.txt) ; do wp post term add $x post_tag 120434 --by=id ; done

That’s it! The same way you could restore a deleted category. If you have backups, which all sites should have, every problem has a solution.

#Change the Parents for a Given Set of Categories

If you want to change the parent of a category, you can easily do it from the wp-admin of your site or with the following WP-CLI command:

wp term update category 134 --parent=53

134 is the ID of the current category and 53 is the ID of the category you want to set as parent.

Let’s say you want to change the parent for a list of categories IDs, for example you have some similar categories and you want to group them together under a descriptive parent category:

for x in $(cat www/wp-content/uploads/categories_list.txt) ; do wp term update category $x --parent=53 ; done

This command will take all the categories IDs from your list and update their parent category to a new one, in this case the category with the ID 53. 

#Convert a List of Categories into Tags

Since WP-CLI version 2.2.0, you can use the wp term migrate command to migrate a term of a taxonomy to another taxonomy, for example convert a category to a tag or vice versa. Here is an example of how to convert a list of categories into tags:

for x in $(cat www/wp-content/uploads/category_list.txt) ; do wp term migrate $x --from=category --to=post_tag ; done

The category_list.txt file contains the IDs of the categories you want to convert. In a similar way you can convert post tags to categories, simply switch the “–from” and “–to” attributes.

#Contribute

If you’ve crafted a wp term command to solve a specific issue for your site, we’d be happy to include your use case in our series, simply drop us an email at support@presslabs.com.