Skip to content

WC CLI Overview

Claudio Sanches edited this page Feb 26, 2021 · 7 revisions
Clone this wiki locally

Table of Contents

WooCommerce CLI (WC-CLI) offers the ability to manage WooCommerce (WC) via the command-line, using WP CLI. The documentation here covers the version of WC CLI that started shipping in WC 3.0.0 and later.

WC CLI is powered by the WC REST API, meaning most of what is possible with the REST API can also be achieved via the command-line.

If you're looking for documentation on the WC 2.5 and 2.6's CLI go here.

What is WP-CLI?

For those who have never heard before WP-CLI, here's a brief description extracted from the official website.

WP-CLI is a set of command-line tools for managing WordPress installations. You can update plugins, set up multisite installs and much more, without using a web browser.

WooCommerce Commands

A full listing WC-CLI commands and their accepted arguments can be found on the commands page.

All WooCommerce related commands are grouped into wp wc command. The available commands (as of WC 3.0) are:

$ wp wc
usage: wp wc customer <command>
   or: wp wc customer_download <command>
   or: wp wc order_note <command>
   or: wp wc payment_gateway <command>
   or: wp wc product <command>
   or: wp wc product_attribute <command>
   or: wp wc product_attribute_term <command>
   or: wp wc product_cat <command>
   or: wp wc product_review <command>
   or: wp wc product_shipping_class <command>
   or: wp wc product_tag <command>
   or: wp wc product_variation <command>
   or: wp wc shipping_method <command>
   or: wp wc shipping_zone <command>
   or: wp wc shipping_zone_location <command>
   or: wp wc shipping_zone_method <command>
   or: wp wc shop_coupon <command>
   or: wp wc shop_order <command>
   or: wp wc shop_order_refund <command>
   or: wp wc tax <command>
   or: wp wc tax_class <command>
   or: wp wc tool <command>
   or: wp wc webhook <command>
   or: wp wc webhook_delivery <command>

See 'wp help wc <command>' for more information on a specific command.

Note: When using the commands, you must specify your username or user ID using the --user argument. This is to let the REST API know which user should be used.

You can see more details about the commands using wp help wc or with the --help flag, which explains arguments and subcommands.


wp wc customer --help


  wp wc customer


  wp wc customer <command>


  create      Create a new item.
  delete      Delete an existing item.
  get         Get a single item.
  list        List all items.
  update      Update an existing item.

wp wc customer list --help


  wp wc customer list


  List all items.


  wp wc customer list [--context=<context>] [--page=<page>]
  [--per_page=<per_page>] [--search=<search>] [--exclude=<exclude>]
  [--include=<include>] [--offset=<offset>] [--order=<order>]
  [--orderby=<orderby>] [--email=<email>] [--role=<role>] [--fields=<fields>]
  [--field=<field>] [--format=<format>]


    Scope under which the request is made; determines fields present in

    Current page of the collection.

    Maximum number of items to be returned in result set.

    Limit results to those matching a string.

    Ensure result set excludes specific IDs.

    Limit result set to specific IDs.

    Offset the result set by a specific number of items.

    Order sort attribute ascending or descending.

    Sort collection by object attribute.

    Limit result set to resources with a specific email.

    Limit result set to resources with a specific role.

    Limit response to specific fields. Defaults to all fields.

    Get the value of an individual field.

    Render response in a particular format.
    default: table
      - table
      - json
      - csv
      - ids
      - yaml
      - count
      - headers
      - body
      - envelope

Arguments like --context, --fields, --field, --format can be used on any get or list WC CLI command.

The --porcelain argument can be used on any create or update command to just get back the ID of the object, instead of a response.

Updating or creating some fields require passing JSON. These are fields that contain arrays of information. For example, setting [](billing information) using the customer command. This is just passing key/value pairs.


$ wp wc customer create --email='me@woo.local' --user=1 --billing='{"first_name":"Justin","last_name":"S","company":"Automattic"}' --password='he llo'

Success: Created customer 16.

$ wp wc customer get 16 --user=1

| id                 | 16                                                                                                                                                             |
| date_created       | 2016-12-09T20:07:35                                                                                                                                            |
| date_modified      | 2016-12-09T20:07:35                                                                                                                                            |
| email              | me@woo.local                                                                                                                                                   |
| first_name         |                                                                                                                                                                |
| last_name          |                                                                                                                                                                |
| role               | customer                                                                                                                                                       |
| username           | me                                                                                                                                                             |
| billing            | {"first_name":"Justin","last_name":"S","company":"Automattic","address_1":"","address_2":"","city":"","state":"","postcode":"","country":"","email":"","phone" |
|                    | :""}                                                                                                                                                           |
| shipping           | {"first_name":"","last_name":"","company":"","address_1":"","address_2":"","city":"","state":"","postcode":"","country":""}                                    |
| is_paying_customer | false                                                                                                                                                          |
| meta_data          |                                                                     |
| orders_count       | 0                                                                                                                                                              |

| total_spent        | 0.00                                                                                                                                                           |
| avatar_url         |                                                                                             |


Full documentation for every command is available using --help. Below are some example commands to show what the CLI can do.

All the examples below use user ID 1 (usually an admin account), but you should replace that with your own user account.

You can also find other examples (without output) by looking at the testing files for our CLI tests:

Each command will have a .feature file. Here are some payment gateway commands, for example:


Clear the product/shop transients cache.

$ wp wc tool run clear_transients --user=1


Success: Updated system_status_tool clear_transients.


List all system tools.

$ wp wc tool list --user=1


| id                         | name                             | action                        | description                                                                       |
| clear_transients           | WC transients                    | Clear transients              | This tool will clear the product/shop transients cache.                           |
| clear_expired_transients   | Expired transients               | Clear expired transients      | This tool will clear ALL expired transients from WordPress.                       |
| delete_orphaned_variations | Orphaned variations              | Delete orphaned variations    | This tool will delete all variations which have no parent.                        |
| recount_terms              | Term counts                      | Recount terms                 | This tool will recount product terms - useful when changing your settings in a wa |
|                            |                                  |                               | y which hides products from the catalog.                                          |
| reset_roles                | Capabilities                     | Reset capabilities            | This tool will reset the admin, customer and shop_manager roles to default. Use t |
|                            |                                  |                               | his if your users cannot access all of the WooCommerce admin pages.               |
| clear_sessions             | Customer sessions                | Clear all sessions            | <strong class="red">Note:</strong> This tool will delete all customer session dat |
|                            |                                  |                               | a from the database, including any current live carts.                            |
| install_pages              | Install WooCommerce pages        | Install pages                 | <strong class="red">Note:</strong> This tool will install all the missing WooComm |
|                            |                                  |                               | erce pages. Pages already defined and set up will not be replaced.                |
| delete_taxes               | Delete all WooCommerce tax rates | Delete ALL tax rates          | <strong class="red">Note:</strong> This option will delete ALL of your tax rates, |
|                            |                                  |                               |  use with caution.                                                                |
| reset_tracking             | Reset usage tracking settings    | Reset usage tracking settings | This will reset your usage tracking settings, causing it to show the opt-in banne |
|                            |                                  |                               | r again and not sending any data.                                                 |


Create a customer

$ wp wc customer create --email='woo@woo.local' --user=1 --billing='{"first_name":"Bob","last_name":"Tester","company":"Woo", "address_1": "123 Main St.", "city":"New York", "state:": "NY", "country":"USA"}' --shipping='{"first_name":"Bob","last_name":"Tester","company":"Woo", "address_1": "123 Main St.", "city":"New York", "state:": "NY", "country":"USA"}' --password='hunter2' --username='mrbob' --first_name='Bob' --last_name='Tester'


Success: Created customer 17.


Get a customer in CSV format

$ wp wc customer get 17 --user=1 --format=csv


billing,"{""first_name"":""Bob"",""last_name"":""Tester"",""company"":""Woo"",""address_1"":""123 Main St."",""address_2"":"""",""city"":""New York"",""state"":"""",""postcode"":"""","
shipping,"{""first_name"":""Bob"",""last_name"":""Tester"",""company"":""Woo"",""address_1"":""123 Main St."",""address_2"":"""",""city"":""New York"",""state"":"""",""postcode"":"""",


Add a customer note on order 355.

$ wp wc order_note create 355 --note="Great repeat customer" --customer_note=true --user=1


Success: Created order_note 286.


Get an order note.

$ wp wc order_note get 355 286 --user=1


| Field         | Value                 |
| id            | 286                   |
| date_created  | 2016-12-09T20:27:26   |
| note          | Great repeat customer |
| customer_note | true                  |


Update a coupon.

$ wp wc shop_coupon update 45 --amount='10' --discount_type='percent' --free_shipping=true --user=1


Success: Updated shop_coupon 45.


Get a coupon.

$ wp wc shop_coupon get 45 --user=1


| Field                       | Value               |

| id                          | 45                  |
| code                        | hello               |
| amount                      | 10.00               |
| date_created                | 2016-08-09T17:37:28 |
| date_modified               | 2016-12-09T20:30:32 |
| discount_type               | percent             |
| description                 | Yay                 |
| date_expires                | 2016-10-22T00:00:00 |
| usage_count                 | 2                   |
| individual_use              | false               |
| product_ids                 | []                  |
| excluded_product_ids        | []                  |
| usage_limit                 | null                |
| usage_limit_per_user        | null                |
| limit_usage_to_x_items      | null                |
| free_shipping               | true                |
| product_categories          | []                  |
| excluded_product_categories | []                  |
| exclude_sale_items          | false               |
| minimum_amount              | 0.00                |
| maximum_amount              | 0.00                |
| email_restrictions          | []                  |
| used_by                     | ["1","1"]           |
| meta_data                   | []                  |

Frequently Asked Questions

I get a 401 error when using commands, what do I do?

If you are getting a 401 error, for example like Error: Sorry, you cannot list resources. {"status":401}

You are trying to use the command unauthenticated. The WooCommerce CLI as of 3.0 requires you to provide a proper user to run the action as. Pass in your user ID using the --user flag.

I am trying to update a list of X but it's not saving

Some 'lists' are objects, for example, if you want to set categories for a product the REST API expects an array of objects:

So to set this you would use JSON like this:

wp wc product create --name='Product Name' --categories='[ { "id" : 21 } ]' --user=admin