claude-plugins/wordpress/skills/woocommerce-cli/SKILL.md

name, description

name	description
woocommerce-cli	Gestão WooCommerce via WP-CLI no servidor CWP. Cobre produtos, encomendas, clientes, shipping, gateways de pagamento, importação/exportação em massa e automação.

/woocommerce-cli — WooCommerce via WP-CLI no CWP

Gestão completa de lojas WooCommerce via linha de comandos no servidor CWP. Cobre produtos, encomendas, clientes, configuração, automação e scripting.

Servidor: server.descomplicar.pt (176.9.3.158) | porta SSH: 9443 Manual: Hub/06-Operacoes/Documentacao/Manuais/WooCommerce com WP-CLI_ Guia Completo.md Skill relacionada: /woocommerce — desenvolvimento e extensões WooCommerce

---

Contexto CWP — Regras Obrigatórias

# 1. SEMPRE prefixar com PHP completo
# 2. SEMPRE --allow-root (CWP executa como root)
# 3. SEMPRE --user=1 em operações de escrita (mapeamento REST API)
# 4. SEMPRE --path= (múltiplos sites no mesmo servidor)

# Formato base
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc <ENTIDADE> <OP> \
  --user=1 --allow-root --path=/home/USER/public_html

# Variável de conveniência para scripts
PATH_WP="/home/USER/public_html"
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"
$WP wc product list --user=1

Versões PHP disponíveis

Alias	PHP	Path
wp74	7.4	/opt/alt/php-fpm74/usr/bin/php
wp82	8.2	/opt/alt/php-fpm82/usr/bin/php
wp83	8.3	/opt/alt/php-fpm83/usr/bin/php (recomendado)

Parâmetros essenciais WC CLI

Parâmetro	Uso
--user=1	Obrigatório em escrita (autenticação REST API)
--porcelain	Retorna apenas ID numérico (para scripts)
--format=table|json|csv|ids	Formato do output
--fields=id,name,price	Limitar campos (reduz memória)
--per_page=100	Limite máximo da API (paginar para mais)
--force	Eliminar definitivamente (sem lixo)

---

Produtos

Operações Comuns

PATH_WP="/home/USER/public_html"

# Listar produtos
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product list \
  --user=1 --fields=id,name,price,stock_quantity --format=table \
  --allow-root --path=$PATH_WP

# Criar produto simples
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="Produto Exemplo" \
  --type=simple \
  --regular_price="29.99" \
  --sku="PROD-001" \
  --manage_stock=true \
  --stock_quantity=100 \
  --status=publish \
  --allow-root --path=$PATH_WP

# Actualizar preço e stock
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product update 456 \
  --user=1 \
  --regular_price="34.99" \
  --stock_quantity=50 \
  --allow-root --path=$PATH_WP

# Eliminar definitivamente
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product delete 456 \
  --user=1 --force --allow-root --path=$PATH_WP

Produto Variável (capturar ID)

# 1. Criar produto pai (--porcelain retorna só o ID)
PARENT_ID=$(/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 --name="T-Shirt" --type=variable \
  --attributes='[{"name":"Tamanho","variation":true,"visible":true,"options":["S","M","L","XL"]}]' \
  --porcelain --allow-root --path=$PATH_WP)

# 2. Criar variação
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product_variation create $PARENT_ID \
  --user=1 \
  --regular_price="24.99" \
  --sku="TSHIRT-M" \
  --attributes='[{"name":"Tamanho","option":"M"}]' \
  --manage_stock=true --stock_quantity=30 \
  --allow-root --path=$PATH_WP

Actualização em Massa por SKU

#!/bin/bash
PATH_WP="/home/USER/public_html"
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"

IDS=$($WP wc product list --user=1 --sku="TSHIRT-*" --format=ids)
for ID in $IDS; do
  $WP wc product update $ID --user=1 --stock_quantity=200 --porcelain
done

Exportar Catálogo

/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product list \
  --user=1 --per_page=5000 --format=csv \
  --allow-root --path=$PATH_WP \
  > /home/USER/catalogo_$(date +%Y%m%d).csv

---

Encomendas

PATH_WP="/home/USER/public_html"

# Listar encomendas em processamento
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_order list \
  --user=1 --status=processing \
  --fields=id,total,date_created \
  --allow-root --path=$PATH_WP

# Actualizar estado
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_order update 355 \
  --user=1 --status=completed \
  --allow-root --path=$PATH_WP

# Adicionar nota ao cliente
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc order_note create 355 \
  --user=1 \
  --note="Encomenda expedida. Rastreio: PT-99887766." \
  --customer_note=true \
  --allow-root --path=$PATH_WP

# Conclusão massiva de todas as encomendas em processamento
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"
for ID in $($WP wc shop_order list --user=1 --status=processing --format=ids); do
  $WP wc shop_order update $ID --user=1 --status=completed --porcelain
done

---

Clientes

# Listar clientes com métricas
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc customer list \
  --user=1 --fields=id,email,orders_count,total_spent \
  --format=table --allow-root --path=$PATH_WP

# Criar cliente
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc customer create \
  --user=1 \
  --email="cliente@exemplo.pt" \
  --first_name="João" \
  --last_name="Silva" \
  --billing='{"address_1":"Rua X","city":"Lisboa","postcode":"1000-001","country":"PT"}' \
  --allow-root --path=$PATH_WP

---

Configurações da Loja

PATH_WP="/home/USER/public_html"

# Listar ferramentas disponíveis
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc tool list \
  --user=1 --fields=id,name --allow-root --path=$PATH_WP

# Sequência de limpeza pós-alterações (executar sempre após mudanças)
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"
$WP wc tool run clear_transients --user=1         # Limpar transients WC
$WP wc tool run recount_terms --user=1            # Recalcular contadores
$WP wc tool run delete_orphaned_variations --user=1 # Variações órfãs
$WP cache flush                                     # Object cache
$WP rewrite flush                                   # Rewrite rules

# Listar payment gateways
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc payment_gateway list \
  --user=1 --fields=id,title,enabled --allow-root --path=$PATH_WP

# Desactivar gateway (emergência)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc payment_gateway update paypal \
  --user=1 --enabled=false --allow-root --path=$PATH_WP

---

Cron do Sistema (CWP)

Desactivar WP-Cron virtual — adicionar em wp-config.php:

define('DISABLE_WP_CRON', true);

Configurar cron real (crontab -e como root):

* * * * * /opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp cron event run --due-now --quiet --allow-root --path=/home/USER/public_html > /dev/null 2>&1

---

Erros Comuns

Erro	Causa	Solução
Error: This does not appear to be a WooCommerce installation	WooCommerce inactivo	wp plugin activate woocommerce
Error: Sorry, you cannot list resources	Falta --user=	Adicionar --user=1
PHP Fatal error: memory	Catálogo grande	Adicionar -d memory_limit=2G antes de /usr/local/bin/wp
wp wc update não actualiza BD	Bug conhecido	wp option update woocommerce_db_version "X.X.X" manual
Wizard de onboarding bloqueia	Sem comando CLI	wp option update woocommerce_task_list_hidden "yes"

---

Recursos Adicionais

Referência Completa

• references/commands.md — Todos os tipos de produto (variável, externo, agrupado, virtual, downloadable), shipping zones completo, tributação, cupões, WP All Import, scripts de automação

Manual Hub

• Hub/06-Operacoes/Documentacao/Manuais/WooCommerce com WP-CLI_ Guia Completo.md — Guia completo adaptado para CWP (v2.0)

Skills Relacionadas

• /woocommerce — Desenvolvimento WooCommerce (PHP, hooks, extensões)
• /wp-cli — WP-CLI geral no CWP (core, plugins, temas, BD)

---

WooCommerce CLI no CWP | Descomplicar® | v1.0.0 | 18-02-2026