Cuando un sitio WordPress empieza a fallar, el panel de administración no siempre es el mejor lugar para investigar. A veces el problema está en un plugin, en una consulta a base de datos, en una configuración del servidor o incluso en una tarea programada que rompe la carga de páginas. En esos casos, WP-CLI se convierte en una herramienta especialmente útil para diagnosticar el origen del error desde la consola, con más control y menos ruido visual.
Si ya has dado tus primeros pasos con la terminal y conoces comandos básicos de gestión, esta guía te ayudará a ir un nivel más allá. La idea no es repetir lo esencial sobre qué es WP-CLI o cómo se instala, sino mostrar cómo usarlo como una herramienta de debugging para aislar incidencias, revisar información técnica y acelerar la resolución de problemas.
Por qué WP-CLI es tan útil para depurar
Depurar desde consola tiene una ventaja clara: puedes trabajar sin depender del frontend ni del escritorio de WordPress. Eso es clave cuando hay pantallas en blanco, errores fatales o conflictos que impiden cargar el administrador. Además, la salida de los comandos es directa y puede integrarse en scripts, logs o procesos de soporte.
WP-CLI también resulta especialmente práctico en entornos remotos, despliegues automatizados y servidores gestionados. Si trabajas con varias instalaciones, conviene apoyarse en métodos organizados como los aliases en WP-CLI, algo que facilita repetir diagnósticos en diferentes sitios sin perder tiempo.
Activar el modo debug de WordPress desde consola
Uno de los primeros pasos para depurar WordPress consiste en habilitar el modo de depuración. WordPress ofrece constantes como WP_DEBUG, WP_DEBUG_LOG y WP_DEBUG_DISPLAY, que permiten registrar errores y controlar si se muestran en pantalla.
Con WP-CLI, puedes inspeccionar y modificar estos valores sin entrar manualmente por FTP o el editor de archivos. Antes de tocar nada, haz una copia de seguridad o asegúrate de tener un snapshot válido. Si no la tienes reciente, revisa primero cómo realizar un backup de WordPress con WP-CLI.
# Ver el valor actual de una constante en wp-config.php
wp config get WP_DEBUG
# Activar el registro de errores
wp config set WP_DEBUG true --raw
# Guardar los errores en el archivo debug.log
wp config set WP_DEBUG_LOG true --raw
# Evitar que los errores se muestren en pantalla
wp config set WP_DEBUG_DISPLAY false --rawEstos cambios son muy útiles cuando el sitio sigue funcionando, pero sospechas que algo está generando warnings, notices o errores fatales invisibles para el usuario final.
Revisar errores y logs sin salir de la terminal
Una vez activado el registro de errores, el siguiente paso es revisar qué está pasando. En muchos entornos de WordPress, el archivo debug.log se ubica dentro de wp-content. Desde la consola puedes inspeccionarlo con herramientas estándar del sistema operativo.
# Ver las últimas líneas del log
tail -n 50 wp-content/debug.log
# Seguir el archivo en tiempo real mientras reproduces el error
tail -f wp-content/debug.logEste enfoque permite reproducir el fallo y observar el mensaje exacto en paralelo. Es especialmente útil para detectar rutas rotas, funciones obsoletas, conflictos de hooks o llamadas a clases que no existen.
Si el problema parece estar relacionado con cambios recientes en la base de datos, puede ayudarte repetir determinadas comprobaciones con comandos de exportación e importación. En ese caso, es recomendable conocer también la guía sobre cómo exportar e importar la base de datos con WP-CLI.
Comprobar el estado de plugins y temas sospechosos
Uno de los motivos más frecuentes de errores en WordPress es un plugin incompatible o un tema con código defectuoso. WP-CLI permite desactivar componentes rápidamente, incluso cuando el panel no responde.
# Ver qué plugins están activos
wp plugin list --status=active
# Desactivar un plugin concreto
wp plugin deactivate nombre-del-plugin
# Desactivar todos los plugins para aislar el problema
wp plugin deactivate --all
# Cambiar temporalmente a un tema por defecto
wp theme activate twentytwentyfourEsta técnica es básica, pero muy efectiva. Si el sitio deja de fallar tras desactivar un plugin, ya tienes una pista clara. Para una gestión más detallada, te puede interesar repasar cómo instalar y activar plugins con WP-CLI o cómo instalar y cambiar temas con WP-CLI, ya que entender el ciclo completo ayuda a depurar con más criterio.
Usar wp eval para probar código y detectar fallos
Una de las funciones más potentes para depurar WordPress es wp eval, que ejecuta fragmentos de PHP dentro del contexto real de WordPress. Esto permite verificar funciones, constantes, opciones o consultas sin tener que crear un plugin temporal.
# Probar si una opción existe
wp eval 'var_dump(get_option("blogname"));'
# Comprobar el estado de una función o clase
wp eval 'var_dump(function_exists("wc_get_product"));'
# Ejecutar una prueba simple de carga
wp eval 'echo get_stylesheet();'Con este tipo de comandos puedes confirmar si el problema está en WordPress, en un plugin concreto o en una incompatibilidad de versión. También es una forma rápida de validar hipótesis cuando el fallo aparece solo en ciertas condiciones.
Eso sí, conviene usar wp eval con prudencia. Si ejecutas código que modifica datos, hazlo solo cuando entiendas bien el impacto. En contextos de mantenimiento, es preferible combinar estas pruebas con una revisión previa de la base de datos y con comandos de optimización, como los que se explican en cómo optimizar la base de datos de WordPress desde consola.
Auditar tareas programadas y procesos que fallan en segundo plano
Muchos errores de WordPress no aparecen en pantalla, pero degradan el sitio por dentro. Tareas cron atascadas, acciones agendadas que no se ejecutan o jobs de plugins que fallan pueden generar lentitud, comportamientos extraños o avisos recurrentes en logs.
WP-CLI permite inspeccionar las tareas cron registradas y ejecutar eventos de forma manual para verificar si el problema se reproduce fuera del horario habitual.
# Listar eventos cron programados
wp cron event list
# Ejecutar todos los eventos debidos
wp cron event run --due-now
# Ejecutar un hook específico
wp cron event run nombre_del_hookCuando una tarea falla de forma repetida, este tipo de auditoría ayuda a distinguir si el origen está en WordPress, en el servidor o en una integración externa. Es una buena práctica, además, si ya automatizas tareas con consola y quieres profundizar en WP-CLI y cron.
Buscar valores incorrectos y limpiar estados rotos
En procesos de depuración también es frecuente encontrar opciones corruptas, transients obsoletos o cachés que impiden ver el comportamiento real del sitio. Aunque limpiar caché no siempre resuelve el problema de fondo, sí sirve para eliminar variables y confirmar si el fallo persiste.
Antes de seguir investigando, puede resultar útil vaciar transients o cachés de forma controlada. Si quieres reforzar esa parte del diagnóstico, puedes consultar cómo limpiar la caché y transients con WP-CLI.
En algunos escenarios, incluso conviene comprobar si una URL antigua, un dominio temporal o una ruta mal migrada está provocando el conflicto. Para ello, el flujo de trabajo se complementa bien con buscar y reemplazar URLs en WordPress con WP-CLI, una técnica muy habitual en migraciones y entornos de staging.
Cómo organizar una depuración segura y repetible
Depurar no consiste solo en “probar cosas” hasta dar con el fallo. Lo ideal es seguir un orden: validar logs, reproducir el problema, aislar plugins o temas, revisar cron, comprobar constantes de debug y documentar el resultado. Así evitas perder tiempo y reduces el riesgo de introducir nuevos errores.
Una estrategia recomendable es trabajar siempre de menos a más impacto. Primero lectura de logs, después comprobaciones con wp eval, y solo al final cambios de configuración o desactivaciones globales. En entornos de producción, esta disciplina marca la diferencia entre un diagnóstico limpio y una incidencia mayor.
Errores habituales al depurar con wp-cli
Un error muy común es activar WP_DEBUG sin desactivar la visualización de errores en un sitio público. Eso puede exponer información sensible o romper la experiencia del usuario. Otro fallo frecuente es modificar archivos sin registrar antes una copia de seguridad.
También conviene evitar conclusiones precipitadas. Que un plugin deje de fallar al desactivarlo no significa necesariamente que sea el culpable único: puede existir un conflicto de versiones, una dependencia no satisfecha o un problema de datos heredados.
En ese sentido, WP-CLI da velocidad, pero el criterio técnico sigue siendo esencial. La combinación de consola, logs y pruebas controladas es la forma más sólida de depurar WordPress con precisión.
Conclusión
WP-CLI no solo sirve para administrar WordPress más rápido; también es una herramienta muy potente para diagnosticar incidencias con un enfoque profesional. Al activar el debug, revisar logs, aislar plugins y temas, y probar código dentro del contexto real de WordPress, puedes encontrar el origen de muchos problemas sin depender del panel de administración.
Si ya usas WP-CLI para tareas de gestión, el siguiente paso lógico es integrarlo en tu flujo de soporte y mantenimiento. Y si quieres seguir ampliando tu dominio de la herramienta, merece la pena explorar artículos sobre backups, despliegues, automatización y gestión avanzada.
Fuentes y lecturas recomendadas
Documentación oficial de WP-CLI
Debugging in WordPress – documentación oficial
WordPress Developer Resources: debugging
Deja una respuesta