WP-CLI: criar comandos customizados no WordPress

Atualizado em 19/06/2026

Há tarefas que simplesmente não cabem no navegador: reprocessar 80 mil pedidos, importar um catálogo a partir de um CSV, corrigir metadados em massa, rodar uma limpeza noturna agendada no cron do sistema. Tentar fazer isso por uma tela de admin esbarra em timeout, em limite de memória e na falta de automação. A ferramenta certa para esse tipo de trabalho é o WP-CLI — e o que poucos desenvolvedores exploram é que você pode estender o WP-CLI com os seus próprios comandos, tão integrados quanto os nativos, com ajuda automática, validação de argumentos e barra de progresso. Este guia mostra como.

O que é o WP-CLI

O WP-CLI é a interface de linha de comando oficial do WordPress. Em vez de clicar no painel, você digita comandos como wp plugin update --all, wp user create ou wp db export direto no terminal do servidor. O detalhe que torna tudo isso possível: antes de executar qualquer comando, o WP-CLI carrega o WordPress por completo — o mesmo wp-load.php de uma requisição web. Isso significa que, dentro do seu comando, você tem à disposição todas as funções do núcleo, dos plugins ativos e do tema: get_posts(), wc_get_orders(), wp_insert_user() funcionam exatamente como funcionariam num plugin. O seu comando é, na prática, código WordPress rodando fora do ciclo HTTP.

Registrando um comando: WP_CLI::add_command()

A porta de entrada é o método estático WP_CLI::add_command( $nome, $callable_ou_classe ). O primeiro argumento é o nome que você digitará após wp; o segundo pode ser o nome de uma classe (o padrão recomendado — cada método público vira um subcomando), uma instância, uma função nomeada ou uma closure.

<?php
// Em um plugin ou mu-plugin. Este bloco SÓ roda quando o WP-CLI carrega o WP.
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    // Registramos uma CLASSE: cada método público vira um subcomando.
    // Uso: wp dwp-loja <subcomando> ...
    WP_CLI::add_command( 'dwp-loja', 'DWP_Loja_CLI_Command' );
}

Com isso, wp dwp-loja passa a existir, e cada método público da classe DWP_Loja_CLI_Command vira um subcomando — por exemplo, wp dwp-loja reindexar ou wp dwp-loja exportar. Esse modelo de "uma classe, vários subcomandos" é o que o próprio núcleo usa (compare com wp post list, wp post create...).

O comando como classe, com synopsis via PHPDoc

Cada método público que aceita a assinatura ( $args, $assoc_args ) torna-se um subcomando. O grande recurso do WP-CLI é o synopsis automático: você documenta os parâmetros no PHPDoc do método, e o WP-CLI lê esse comentário para gerar a ajuda (wp help dwp-loja exportar) e validar a entrada antes de o seu código rodar.

<?php
/**
 * Comandos da loja para o WP-CLI.
 */
class DWP_Loja_CLI_Command {

    /**
     * Exporta produtos para um arquivo CSV.
     *
     * ## OPTIONS
     *
     * <arquivo>
     * : Caminho do CSV de saída.
     *
     * [--status=<status>]
     * : Filtra por status do produto.
     * ---
     * default: publish
     * options:
     *   - publish
     *   - draft
     *   - any
     * ---
     *
     * [--limit=<numero>]
     * : Quantidade máxima de produtos. Padrão: todos.
     *
     * [--dry-run]
     * : Simula a operação sem gravar nada no arquivo.
     *
     * ## EXAMPLES
     *
     *     wp dwp-loja exportar produtos.csv --status=publish --limit=500
     *     wp dwp-loja exportar teste.csv --dry-run
     *
     * @when after_wp_load
     */
    public function exportar( $args, $assoc_args ) {
        // ... corpo do comando (veja o próximo bloco) ...
    }
}

Repare em alguns detalhes idiomáticos: <arquivo> entre <> declara um posicional obrigatório; os colchetes em [--status=<status>] indicam que a flag é opcional; o bloco --- com default e options faz o WP-CLI aplicar um valor padrão e recusar valores fora da lista. A anotação @when after_wp_load garante que o comando só execute após o WordPress estar totalmente carregado — o padrão para comandos que usam funções do core.

Lendo argumentos e produzindo saída

Dentro do método, $args traz os posicionais (na ordem) e $assoc_args traz as flags (por chave). Para extrair flags com valor padrão de forma limpa, o WP-CLI oferece \WP_CLI\Utils\get_flag_value(). E, para comunicar com o usuário, use os helpers de saída — eles cuidam de cores, do exit code correto e do comportamento em modo silencioso.

<?php
public function exportar( $args, $assoc_args ) {
    // Posicional obrigatório: o WP-CLI já garantiu que existe (está no synopsis).
    $arquivo = $args[0];

    // Flags com padrão seguro.
    $status  = \WP_CLI\Utils\get_flag_value( $assoc_args, 'status', 'publish' );
    $limit   = (int) \WP_CLI\Utils\get_flag_value( $assoc_args, 'limit', -1 );
    $dry_run = (bool) \WP_CLI\Utils\get_flag_value( $assoc_args, 'dry-run', false );

    if ( ! $dry_run && ! is_writable( dirname( $arquivo ) ) ) {
        // error() imprime em vermelho E encerra com exit code 1 (falha real).
        WP_CLI::error( "Diretório não gravável: " . dirname( $arquivo ) );
    }

    if ( $dry_run ) {
        WP_CLI::warning( 'Modo simulação: nenhum arquivo será gravado.' );
    }

    $ids = get_posts( array(
        'post_type'      => 'product',
        'post_status'    => ( 'any' === $status ) ? 'any' : $status,
        'fields'         => 'ids',
        'posts_per_page' => $limit,
        'no_found_rows'  => true,
    ) );

    WP_CLI::log( sprintf( 'Encontrados %d produtos.', count( $ids ) ) );

    // ... gravação do CSV (omitida) ...

    // success() = verde + exit code 0. É a forma certa de sinalizar "deu certo".
    WP_CLI::success( $dry_run
        ? 'Simulação concluída.'
        : sprintf( '%d produtos exportados para %s', count( $ids ), $arquivo )
    );
}

Tabela: helpers de saída do WP_CLI

Confirmação, barra de progresso e tabelas

Para operações destrutivas, WP_CLI::confirm() pede um "sim" explícito (e respeita a flag --yes para rodar sem interação). Para operações longas, a barra de progresso de \WP_CLI\Utils\make_progress_bar() dá feedback visual; e \WP_CLI\Utils\format_items() imprime dados tabulados em table, csv, json ou yaml.

<?php
public function reindexar( $args, $assoc_args ) {
    // Operação cara: confirme antes (a flag --yes pula isto, útil em cron).
    WP_CLI::confirm( 'Reindexar TODOS os produtos? Isso pode demorar.', $assoc_args );

    $ids   = get_posts( array(
        'post_type'      => 'product',
        'post_status'    => 'any',
        'fields'         => 'ids',
        'posts_per_page' => -1,
        'no_found_rows'  => true,
    ) );
    $total = count( $ids );

    $barra = \WP_CLI\Utils\make_progress_bar( 'Reindexando', $total );

    foreach ( $ids as $id ) {
        // ... reindexa o produto $id ...
        clean_post_cache( $id ); // higiene: impede o cache de objeto de inflar
        $barra->tick();
    }
    $barra->finish();

    WP_CLI::success( sprintf( '%d produtos reindexados.', $total ) );
}

public function relatorio( $args, $assoc_args ) {
    $formato = \WP_CLI\Utils\get_flag_value( $assoc_args, 'format', 'table' );

    $linhas = array(
        array( 'status' => 'publish', 'total' => 1280 ),
        array( 'status' => 'draft',   'total' =>   42 ),
    );

    // Imprime em table/csv/json/yaml conforme --format. Os 3 args:
    // ( formato, itens, colunas )
    \WP_CLI\Utils\format_items( $formato, $linhas, array( 'status', 'total' ) );
}

Onde registrar e como usar em produção

Você pode registrar comandos em qualquer plugin ativo, mas há dois bons lugares: dentro de um plugin próprio (quando o comando faz parte de uma funcionalidade que você distribui) ou em um mu-plugin em wp-content/mu-plugins/ (quando é uma ferramenta interna de manutenção que deve estar sempre disponível e não pode ser desativada por engano). Os casos de uso típicos:

• Operações em massa — corrigir metadados, recalcular totais, migrar dados.
• Importações — ler um CSV/JSON e criar posts, produtos ou usuários.
• Manutenção — limpar transients órfãos, regenerar miniaturas, reindexar buscas.
• Rotinas agendadas — chamar o comando pelo cron do sistema (não o WP-Cron), garantindo execução no horário independentemente de tráfego. Veja o porquê em hooks e nos artigos de agendamento.

# Exemplo de agendamento no crontab do sistema (roda 3h da manhã):
0 3 * * * cd /var/www/seusite && wp dwp-loja reindexar --yes --quiet

# Em scripts, --path evita depender do diretório atual:
wp --path=/var/www/seusite dwp-loja exportar /backups/produtos.csv

Armadilhas comuns

• Esquecer a guarda defined( 'WP_CLI' ). Sem ela, o registro do comando derruba o site no navegador.
• Usar echo/print em vez dos helpers. Você perde cor, exit code correto e o respeito a --quiet/--format. Saída de comando se faz com WP_CLI::log() e amigos.
• Não declarar o synopsis (PHPDoc). Sem ## OPTIONS, o WP-CLI não valida a entrada nem gera ajuda — e você acaba escrevendo validação manual frágil.
• Memória em operações longas. posts_per_page => -1 + cache de objeto crescente = out of memory. Pagine e limpe o cache.
• Operação destrutiva sem confirmação. Sempre use WP_CLI::confirm() (que respeita --yes) e ofereça um --dry-run.
• Assumir o diretório atual. Em cron e deploy, passe --path ou faça cd antes; o WP-CLI precisa achar a instalação.

Boas práticas

• Modele como classe com um subcomando por método público — fica organizado e idiomático.
• Documente tudo no PHPDoc (## OPTIONS, ## EXAMPLES): vira ajuda e validação de graça.
• Implemente --dry-run em qualquer comando que altera dados; rode em simulação antes de valer.
• Processe em lotes e limpe o cache de objeto dentro de loops longos.
• Use o exit code corretamente — error() para falha, success() para êxito — para que a automação a jusante saiba o que aconteceu.
• Para jobs gigantes ou que não podem bloquear o terminal, combine o WP-CLI com uma fila: dispare lotes que o Action Scheduler processa em segundo plano.

Comandos próprios de WP-CLI são uma das ferramentas mais subestimadas do ecossistema: transformam tarefas que seriam horas de cliques (ou scripts perigosos rodando pelo navegador) em operações repetíveis, automatizáveis e seguras. Combinados com um plugin bem estruturado e bons hooks, eles elevam a qualidade de qualquer projeto WordPress sério.