Command-line syntax

This page explains how to format commands and their arguments in documentation. For more information about other code-related documentation, see Code in text, Placeholders, and Code examples.

Command prompt

When you have to show multiple lines of command-line input, initiate each line with the dollar ($) command prompt symbol.

Don’t show the current directory path before the prompt, even if part of the instruction includes creating or changing directories. This is because the directory structure might be different for the user. However, if the general context of the command-line interface changes—such as from the local machine to a remote machine—then add an additional prompt indicator for the new context.

Examples

<br />
$ wp theme activate twentytwentyone<br />

<br />
Success: Switched to &#039;Twenty Twenty-One&#039; theme.<br />

<br />
$ pwd<br />
/srv/www/wordpress-develop.dev<br />
$ cat wp-cli.yml<br />
path: src/<br />

For single-line commands, the command prompt, that is the dollar symbol ($) is optional. However, if you have to show both multi-line and single-line commands, use the command prompt symbol for overall consistency.

Use separate code blocks for command-line instructions that include both input and output lines.

Example

<br />
$ wp cap list &#039;editor&#039; | xargs wp cap add &#039;author&#039;<br />

<br />
Success: Added 24 capabilities to &#039;author&#039; role.<br />

Required commands and arguments

When writing commands and arguments that are required, use code font without brackets, braces, or parentheses.

Examples

<br />
$ wp post list &#8211;post_type=&#039;page&#039; &#8211;format=ids<br />

<br />
$ wp core check-update<br />

For more information, see Anatomy of a command.

Optional arguments

When writing arguments that are optional, enclose the arguments in square brackets. If there is more than one optional argument, enclose each item in its individual set of square brackets.

Example

<br />
$ wp plugin install https://wordpress.org/plugins/gutenberg/ [&#8211;force] [&#8211;activate]<br />

Mutually exclusive arguments

When writing commands where the use has to choose one item, enclose the items in angle brackets (<>; also known as inequality signs). Sometimes the mutually exclusive choices are also enclosed in braces (also known as curly braces). Use vertical bars (also knows as pipes) to separate the items. You can have more than two mutually exclusive items that are separated from each other by pipes.

Example

<br />
$ wp plugin install &lt;plugin|zip|url&gt;<br />

Multiple value arguments

Use an ellipsis (...) to indicate that the user can specify multiple values for the argument.

Examples

<br />
$ wp media import [&#8211;post_id=&lt;post_id&gt;&#8230;]<br />

<br />
$ wp plugin install &lt;plugin|zip|url&gt;&#8230;<br />

Command output

You don’t have to show an output for every command. Only add the output if it is useful; for example, if the user needs to copy a value or needs to verify a value from the output.

If you do show have to show an output, use an introductory phrase to separate the command from the output.

Examples

<br />
$ wp theme status twentytwentyone<br />

<br />
Theme twentytwentyone details:<br />
     Name: Twenty Twenty-One<br />
     Status: Active<br />
     Version: 1.1<br />
     Author: WordPress.org<br />

<br />
$ wp server &#8211;host=localhost.localdomain &#8211;port=80<br />

<br />
PHP 5.6.9 Development Server started at Fri Jan 22 11:32:56 2021<br />
Listening on http://localhost1.localdomain1:80<br />
Document root is /<br />
Press Ctrl-C to quit.<br />

For more information about explaining placeholders in output, see Placeholders in output.

Additional resources

• WP-CLI Handbook
• WP-CLI Commands