WordPress at a glance
Home Handbook WP-CLI Commands

wp menu

Lists, creates, assigns, and deletes the active theme’s navigation menus.

See the Navigation Menus reference in the Theme Handbook.

Commands Description
Creates a new menu.
Deletes one or more menus.
Gets a list of menus.
Gets a list of items associated with a menu.
Adds a post as a menu item.
Adds a taxonomy term as a menu item.
Adds a custom menu item.
Updates a menu item.
Deletes one or more items from a menu.
Lists locations for the current theme.
Assigns a location to a menu.
Removes a location from a menu.

Examples

# Create a new menu
$ wp menu create "My Menu"
Success: Created menu 200.

# List existing menus
$ wp menu list
+---------+----------+----------+-----------+-------+
| term_id | name     | slug     | locations | count |
+---------+----------+----------+-----------+-------+
| 200     | My Menu  | my-menu  |           | 0     |
| 177     | Top Menu | top-menu | primary   | 7     |
+---------+----------+----------+-----------+-------+

# Create a new menu link item
$ wp menu item add-custom my-menu Apple http://apple.com --porcelain
1922

# Assign the 'my-menu' menu to the 'primary' location
$ wp menu location assign my-menu primary
Success: Assigned location to menu.

Source code of the commands


menu

wp menu create

Creates a new menu.

Usage

wp menu create {menu-name} [--porcelain]

You can specify global options and the following:

{menu-name}
A descriptive name for the menu.
[--porcelain]
Output just the new menu id.

Examples

$ wp menu create "My Menu"
Success: Created menu 200.

wp menu delete

Deletes one or more menus.

Usage

wp menu delete {menu}...

You can specify global options and the following:

{menu}...
The name, slug, or term ID for the menu(s).

Examples

$ wp menu delete "My Menu"
Success: 1 menu deleted.

wp menu list

Gets a list of menus.

Usage

wp menu list [--fields={fields}] [--format={format}]

You can specify global options and the following:

[--fields={fields}]
Limit the output to specific object fields.
[--format={format}]

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

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

Available fields

These fields will be displayed by default for each menu:

  • term_id
  • name
  • slug
  • count

These fields are optionally available:

  • term_group
  • term_taxonomy_id
  • taxonomy
  • description
  • parent
  • locations

Examples

$ wp menu list
+---------+----------+----------+-----------+-------+
| term_id | name     | slug     | locations | count |
+---------+----------+----------+-----------+-------+
| 200     | My Menu  | my-menu  |           | 0     |
| 177     | Top Menu | top-menu | primary   | 7     |
+---------+----------+----------+-----------+-------+
menu

wp menu item list

Gets a list of items associated with a menu.

Usage

wp menu item list {menu} [--fields={fields}] [--format={format}]

You can specify global options and the following:

{menu}
The name, slug, or term ID for the menu.
[--fields={fields}]
Limit the output to specific object fields.
[--format={format}]

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

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

Available fields

These fields will be displayed by default for each menu item:

  • db_id
  • type
  • title
  • link
  • position

These fields are optionally available:

  • menu_item_parent
  • object_id
  • object
  • type
  • type_label
  • target
  • attr_title
  • description
  • classes
  • xfn

Examples

$ wp menu item list main-menu
+-------+-----------+-------------+---------------------------------+----------+
| db_id | type      | title       | link                            | position |
+-------+-----------+-------------+---------------------------------+----------+
| 5     | custom    | Home        | http://example.com              | 1        |
| 6     | post_type | Sample Page | http://example.com/sample-page/ | 2        |
+-------+-----------+-------------+---------------------------------+----------+
menu

wp menu item add-post

Adds a post as a menu item.

Usage

wp menu item add-post {menu} {post-id} [--title={title}] [--link={link}] [--description={description}] [--attr-title={attr-title}] [--target={target}] [--classes={classes}] [--position={position}] [--parent-id={parent-id}] [--porcelain]

You can specify global options and the following:

{menu}
The name, slug, or term ID for the menu.
{post-id}
Post ID to add to the menu.
[--title={title}]
Set a custom title for the menu item.
[--link={link}]
Set a custom url for the menu item.
[--description={description}]
Set a custom description for the menu item.
[--attr-title={attr-title}]
Set a custom title attribute for the menu item.
[--target={target}]
Set a custom link target for the menu item.
[--classes={classes}]
Set a custom link classes for the menu item.
[--position={position}]
Specify the position of this menu item.
[--parent-id={parent-id}]
Make this menu item a child of another menu item.
[--porcelain]
Output just the new menu item id.

Examples

$ wp menu item add-post sidebar-menu 33 --title="Custom Test Post"
Success: Menu item added.
menu

wp menu item add-term

Adds a taxonomy term as a menu item.

Usage

wp menu item add-term {menu} {taxonomy} {term-id} [--title={title}] [--link={link}] [--description={description}] [--attr-title={attr-title}] [--target={target}] [--classes={classes}] [--position={position}] [--parent-id={parent-id}] [--porcelain]

You can specify global options and the following:

{menu}
The name, slug, or term ID for the menu.
{taxonomy}
Taxonomy of the term to be added.
{term-id}
Term ID of the term to be added.
[--title={title}]
Set a custom title for the menu item.
[--link={link}]
Set a custom url for the menu item.
[--description={description}]
Set a custom description for the menu item.
[--attr-title={attr-title}]
Set a custom title attribute for the menu item.
[--target={target}]
Set a custom link target for the menu item.
[--classes={classes}]
Set a custom link classes for the menu item.
[--position={position}]
Specify the position of this menu item.
[--parent-id={parent-id}]
Make this menu item a child of another menu item.
[--porcelain]
Output just the new menu item id.

Examples

$ wp menu item add-term sidebar-menu post_tag 24
Success: Menu item added.
menu

wp menu item add-custom

Adds a custom menu item.

Usage

wp menu item add-custom {menu} {title} {link} [--description={description}] [--attr-title={attr-title}] [--target={target}] [--classes={classes}] [--position={position}] [--parent-id={parent-id}] [--porcelain]

You can specify global options and the following:

{menu}
The name, slug, or term ID for the menu.
{title}
Title for the link.
{link}
Target URL for the link.
[--description={description}]
Set a custom description for the menu item.
[--attr-title={attr-title}]
Set a custom title attribute for the menu item.
[--target={target}]
Set a custom link target for the menu item.
[--classes={classes}]
Set a custom link classes for the menu item.
[--position={position}]
Specify the position of this menu item.
[--parent-id={parent-id}]
Make this menu item a child of another menu item.
[--porcelain]
Output just the new menu item id.

Examples

$ wp menu item add-custom sidebar-menu Apple http://apple.com
Success: Menu item added.
menu

wp menu item update

Updates a menu item.

Usage

wp menu item update {db-id} [--title={title}] [--link={link}] [--description={description}] [--attr-title={attr-title}] [--target={target}] [--classes={classes}] [--position={position}] [--parent-id={parent-id}]

You can specify global options and the following:

{db-id}
Database ID for the menu item.
[--title={title}]
Set a custom title for the menu item.
[--link={link}]
Set a custom url for the menu item.
[--description={description}]
Set a custom description for the menu item.
[--attr-title={attr-title}]
Set a custom title attribute for the menu item.
[--target={target}]
Set a custom link target for the menu item.
[--classes={classes}]
Set a custom link classes for the menu item.
[--position={position}]
Specify the position of this menu item.
[--parent-id={parent-id}]
Make this menu item a child of another menu item.

Examples

$ wp menu item update 45 --title=WordPress --link='http://wordpress.org' --target=_blank --position=2
Success: Menu item updated.
menu

wp menu item delete

Deletes one or more items from a menu.

Usage

wp menu item delete {db-id}...

You can specify global options and the following:

{db-id}...
Database ID for the menu item(s).

Examples

$ wp menu item delete 45
Success: 1 menu item deleted.

wp menu location list

Lists locations for the current theme.

Usage

wp menu location list [--format={format}]

You can specify global options and the following:

[--format={format}]

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

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

Available fields

These fields will be displayed by default for each location:

  • name
  • description

Examples

$ wp menu location list
+----------+-------------------+
| location | description       |
+----------+-------------------+
| primary  | Primary Menu      |
| social   | Social Links Menu |
+----------+-------------------+

wp menu location assign

Assigns a location to a menu.

Usage

wp menu location assign {menu} {location}

You can specify global options and the following:

{menu}
The name, slug, or term ID for the menu.
{location}
Location's slug.

Examples

$ wp menu location assign primary-menu primary
Success: Assigned location primary to menu primary-menu.

wp menu location remove

Removes a location from a menu.

Usage

wp menu location remove {menu} {location}

You can specify global options and the following:

{menu}
The name, slug, or term ID for the menu.
{location}
Location's slug.

Examples

$ wp menu location remove primary-menu primary
Success: Removed location from menu.