WordPress at a glance
Home Handbook WP-CLI Commands

wp term

Manages taxonomy terms and term meta, with create, delete, and list commands.

Commands Description
Lists terms in a taxonomy.
Creates a new term.
Gets details about a term.
Updates an existing term.
Deletes an existing term.
Generates some terms.
Recalculates number of posts assigned to each term.
List all metadata associated with an object.
Get meta field value.
Delete a meta field.
Add a meta field.
Update a meta field.
Get a nested value from a meta field.
Update a nested value for a meta field.

Examples

# Create a new term.
$ wp term create category Apple --description="A type of fruit"
Success: Created category 199.

# Get details about a term.
$ wp term get category 199 --format=json --fields=term_id,name,slug,count
{"term_id":199,"name":"Apple","slug":"apple","count":1}

# Update an existing term.
$ wp term update category 15 --name=Apple
Success: Term updated.

# Get the term's URL.
$ wp term list post_tag --include=123 --field=url
http://example.com/tag/tips-and-tricks

# Delete post category
$ wp term delete category 15
Success: Deleted category 15.

# Recount posts assigned to each categories and tags
$ wp term recount category post_tag
Success: Updated category term count
Success: Updated post_tag term count

Source code of the commands


menu

wp term list

Lists terms in a taxonomy.

Usage

wp term list {taxonomy}... [--{field}={value}] [--field={field}] [--fields={fields}] [--format={format}]

You can specify global options and the following:

{taxonomy}...
List terms of one or more taxonomies
[--{field}={value}]
Filter by one or more fields (see get_terms() $args parameter for a list of fields).
[--field={field}]
Prints the value of a single field for each term.
[--fields={fields}]
Limit the output to specific object fields.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • ids
  • json
  • count
  • yaml

Available fields

These fields will be displayed by default for each term:

  • term_id
  • term_taxonomy_id
  • name
  • slug
  • description
  • parent
  • count

These fields are optionally available:

  • url

Examples

# List post categories
$ wp term list category --format=csv
term_id,term_taxonomy_id,name,slug,description,parent,count
2,2,aciform,aciform,,0,1
3,3,antiquarianism,antiquarianism,,0,1
4,4,arrangement,arrangement,,0,1
5,5,asmodeus,asmodeus,,0,1
# List post tags
$ wp term list post_tag --fields=name,slug
+-----------+-------------+
| name      | slug        |
+-----------+-------------+
| 8BIT      | 8bit        |
| alignment | alignment-2 |
| Articles  | articles    |
| aside     | aside       |
+-----------+-------------+
menu

wp term create

Creates a new term.

Usage

wp term create {taxonomy} {term} [--slug={slug}] [--description={description}] [--parent={term-id}] [--porcelain]

You can specify global options and the following:

{taxonomy}
Taxonomy for the new term.
{term}
A name for the new term.
[--slug={slug}]
A unique slug for the new term. Defaults to sanitized version of name.
[--description={description}]
A description for the new term.
[--parent={term-id}]
A parent for the new term.
[--porcelain]
Output just the new term id.

Examples

# Create a new category "Apple" with a description.
$ wp term create category Apple --description="A type of fruit"
Success: Created category 199.
menu

wp term get

Gets details about a term.

Usage

wp term get {taxonomy} {term} [--by={field}] [--field={field}] [--fields={fields}] [--format={format}]

You can specify global options and the following:

{taxonomy}
Taxonomy of the term to get
{term}
ID or slug of the term to get
[--by={field}]

Explicitly handle the term value as a slug or id.
Default: id
Can be:

  • slug
  • id
[--field={field}]
Instead of returning the whole term, returns the value of a single field.
[--fields={fields}]
Limit the output to specific fields. Defaults to all fields.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • json
  • yaml

Examples

# Get details about a category with id 199.
$ wp term get category 199 --format=json
{"term_id":199,"name":"Apple","slug":"apple","term_group":0,"term_taxonomy_id":199,"taxonomy":"category","description":"A type of fruit","parent":0,"count":0,"filter":"raw"}
# Get details about a category with slug apple.
$ wp term get category apple --by=slug --format=json
{"term_id":199,"name":"Apple","slug":"apple","term_group":0,"term_taxonomy_id":199,"taxonomy":"category","description":"A type of fruit","parent":0,"count":0,"filter":"raw"}
menu

wp term update

Updates an existing term.

Usage

wp term update {taxonomy} {term} [--by={field}] [--name={name}] [--slug={slug}] [--description={description}] [--parent={term-id}]

You can specify global options and the following:

{taxonomy}
Taxonomy of the term to update.
{term}
ID or slug for the term to update.
[--by={field}]

Explicitly handle the term value as a slug or id.
Default: id
Can be:

  • slug
  • id
[--name={name}]
A new name for the term.
[--slug={slug}]
A new slug for the term.
[--description={description}]
A new description for the term.
[--parent={term-id}]
A new parent for the term.

Examples

# Change category with id 15 to use the name "Apple"
$ wp term update category 15 --name=Apple
Success: Term updated.
# Change category with slug apple to use the name "Apple"
$ wp term update category apple --by=slug --name=Apple
Success: Term updated.
menu

wp term delete

Deletes an existing term.

Errors if the term doesn't exist, or there was a problem in deleting it.

Usage

wp term delete {taxonomy} {term}... [--by={field}]

You can specify global options and the following:

{taxonomy}
Taxonomy of the term to delete.
{term}...
One or more IDs or slugs of terms to delete.
[--by={field}]

Explicitly handle the term value as a slug or id.
Default: id
Can be:

  • slug
  • id

Examples

# Delete post category by id
$ wp term delete category 15
Deleted category 15.
Success: Deleted 1 of 1 terms.
# Delete post category by slug
$ wp term delete category apple --by=slug
Deleted category 15.
Success: Deleted 1 of 1 terms.
# Delete all post tags
$ wp term list post_tag --field=term_id | xargs wp term delete post_tag
Deleted post_tag 159.
Deleted post_tag 160.
Deleted post_tag 161.
Success: Deleted 3 of 3 terms.
menu

wp term generate

Generates some terms.

Creates a specified number of new terms with dummy data.

Usage

wp term generate {taxonomy} [--count={number}] [--max_depth={number}] [--format={format}]

You can specify global options and the following:

{taxonomy}
The taxonomy for the generated terms.
[--count={number}]
How many terms to generate?
Default: 100
[--max_depth={number}]
Generate child terms down to a certain depth.
Default: 1
[--format={format}]

Render output in a particular format.
Default: progress
Can be:

  • progress
  • ids

Examples

# Generate post categories.
$ wp term generate category --count=10
Generating terms  100% [=========] 0:02 / 0:02
# Add meta to every generated term.
$ wp term generate category --format=ids --count=3 | xargs -d ' ' -I % wp term meta add % foo bar
Success: Added custom field.
Success: Added custom field.
Success: Added custom field.
menu

wp term recount

Recalculates number of posts assigned to each term.

In instances where manual updates are made to the terms assigned to posts in the database, the number of posts associated with a term can become out-of-sync with the actual number of posts.

This command runs wp_update_term_count() on the taxonomy's terms to bring the count back to the correct value.

Usage

wp term recount {taxonomy}...

You can specify global options and the following:

{taxonomy}...
One or more taxonomies to recalculate.

Examples

# Recount posts assigned to each categories and tags
$ wp term recount category post_tag
Success: Updated category term count.
Success: Updated post_tag term count.
# Recount all listed taxonomies
$ wp taxonomy list --field=name | xargs wp term recount
Success: Updated category term count.
Success: Updated post_tag term count.
Success: Updated nav_menu term count.
Success: Updated link_category term count.
Success: Updated post_format term count.
menu

wp term meta list

List all metadata associated with an object.

Usage

wp term meta list {id} [--keys={keys}] [--fields={fields}] [--format={format}] [--orderby={fields}] [--order={order}]

You can specify global options and the following:

{id}
ID for the object.
[--keys={keys}]
Limit output to metadata of specific keys.
[--fields={fields}]
Limit the output to specific row fields. Defaults to id,meta_key,meta_value.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • json
  • yaml
  • count
[--orderby={fields}]

Set orderby which field.
Default: id
Can be:

  • id
  • meta_key
  • meta_value
[--order={order}]

Set ascending or descending order.
Default: asc
Can be:

  • asc
  • desc
menu

wp term meta get

Get meta field value.

Usage

wp term meta get {id} {key} [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to get.
[--format={format}]

Get value in a particular format.
Default: var_export
Can be:

  • var_export
  • json
  • yaml

wp term meta delete

Delete a meta field.

Usage

wp term meta delete {id} [{key}] [{value}] [--all]

You can specify global options and the following:

{id}
The ID of the object.
[{key}]
The name of the meta field to delete.
[{value}]
The value to delete. If omitted, all rows with key will deleted.
[--all]
Delete all meta for the object.

wp term meta add

Add a meta field.

Usage

wp term meta add {id} {key} [{value}] [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to create.
[{value}]
The value of the meta field. If omitted, the value is read from STDIN.
[--format={format}]

The serialization format for the value.
Default: plaintext
Can be:

  • plaintext
  • json

wp term meta update

Update a meta field.

Usage

wp term meta update {id} {key} [{value}] [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to update.
[{value}]
The new value. If omitted, the value is read from STDIN.
[--format={format}]

The serialization format for the value.
Default: plaintext
Can be:

  • plaintext
  • json

wp term meta pluck

Get a nested value from a meta field.

Usage

wp term meta pluck {id} {key} {key-path}... [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to get.
{key-path}...
The name(s) of the keys within the value to locate the value to pluck.
[--format={format}]
The output format of the value.
--- Default: plaintext
Can be:
  • plaintext
  • json
  • yaml

wp term meta patch

Update a nested value for a meta field.

Usage

wp term meta patch {action} {id} {key} {key-path}... [{value}] [--format={format}]

You can specify global options and the following:

{action}

Patch action to perform.

Can be:

  • insert
  • update
  • delete
{id}
The ID of the object.
{key}
The name of the meta field to update.
{key-path}...
The name(s) of the keys within the value to locate the value to patch.
[{value}]
The new value. If omitted, the value is read from STDIN.
[--format={format}]

The serialization format for the value.
Default: plaintext
Can be:

  • plaintext
  • json