Uso de la CLI

Al iniciar entras en la CLI interactiva y puedes escribir tareas en lenguaje natural. El prompt muestra el estado actual con el formato [modo][nombre-agent] > , por ejemplo [plan][code] > .

Comandos integrados

Comando	Descripción
/plan	Cambiar a modo plan (exploración de solo lectura + propuesta de plan)
/interactive	Cambiar a modo interactivo con aprobación (predeterminado)
/auto	Cambiar a modo totalmente automático (sin aprobación, alto riesgo)
/discuss	Cambiar a modo debate (conversación de solo lectura)
/mode	Mostrar el modo actual
/connect	Conectar el LLM (elegir provider → key → actualizar modelos → esfuerzo de razonamiento)
/connect rm	Borrar la configuración de conexión (volver a las variables de entorno)
/providers	Listar los proveedores LLM configurados (▶ marca el activo)
/use <n.º|id>	Cambiar el proveedor activo
/rm <n.º|id>	Eliminar un proveedor
/link	Asistente de conexión de cuenta (dirección del Hub + correo/teléfono + contraseña o código SMS)
/link <código> [dirección Hub]	Conectar este nodo al centro de usuario con un código de un solo uso
/sessions	Listar conversaciones guardadas y elegir una para restaurar (muestra los últimos mensajes)
/history	Listar las instrucciones del usuario en la conversación actual
/model <id>	Cambiar el modelo LLM
/agent <name>	Cambiar de agent (Prompt + modelo opcional sincronizado)
/agents	Listar todos los agent (el actual resaltado)
/agent add <name> <prompt...>	Añadir un agent personalizado
/agent edit <name> <prompt...>	Modificar el Prompt del agent (el actual se recarga en caliente)
/agent rm <name>	Eliminar un agent
/agent show [name]	Ver el detalle del agent
/mcp	Listar servidores MCP y su estado de conexión
/mcp add <name> stdio <cmd...>|http <url>	Añadir y conectar un servidor MCP (inyecta las herramientas)
/mcp rm|enable|disable|refresh [name]	Eliminar / activar / desactivar / actualizar la lista de herramientas
/tools	Listar todas las herramientas (origen, riesgo, estado)
/tool add <name> <cmd...>	Añadir una herramienta de comando (ejecuta un comando de shell)
/tool rm|disable|enable <name>	Eliminar / desactivar / activar una herramienta
/clear	Vaciar la conversación actual
quit / exit	Salir
reset	Reiniciar la conversación
Escribir + Enter durante la ejecución	Añadir información a la tarea actual (se aplica en la siguiente iteración)
ESC dos veces durante la ejecución	Interrumpir la tarea actual

Ejemplos de tareas habituales

Escribe en lenguaje natural, por ejemplo:

> Inicializa un proyecto TypeScript en el directorio actual
> Lee el código de src/ e indica posibles problemas
> Renombra todos los .json de logs/ a .json.bak
> Ejecuta las pruebas y corrige los casos que fallan

Cuando haya que modificar archivos o ejecutar comandos, en modo interactivo aparece una tarjeta de aprobación y espera tu confirmación.

Modos de ejecución

Modo	Comportamiento
discuss	Solo lectura; prohíbe toda escritura y ejecución
plan	Solo lectura; prohíbe toda escritura y ejecución, orientado a propuestas de plan
interactive	Las operaciones con efectos secundarios requieren aprobación cada vez (predeterminado)
auto	Permite todas las operaciones con efectos secundarios (alto riesgo, bajo tu responsabilidad)

Tarjetas de aprobación

En modo interactivo, la tarjeta admite:

• Y permitir una vez
• A permitir siempre esta herramienta
• D rechazar
• run_shell admite además C para permitir siempre este comando (lista por comando concreto; más seguro que autorizar toda la herramienta)

Información adicional en ejecución (steering)

Durante la ejecución puedes añadir indicaciones sin esperar a que termine: escribe y pulsa Enter; el mensaje se inyecta como mensaje de usuario en el hueco de la siguiente iteración y el agent lo incorpora al continuar.

Para empezar otra tarea, espera a que termine la actual o pulsa ESC dos veces para interrumpirla. (Si hay una aprobación o pregunta pendiente, la entrada se usa primero como respuesta a esa aprobación o pregunta).

Gestión de conversaciones

• /sessions lista las conversaciones guardadas y permite restaurar una; al cambiar muestra los últimos mensajes para retomar el trabajo.
• /clear vacía la conversación actual; reset reinicia su estado.
• /history lista las instrucciones del usuario en la conversación actual para repasar el contexto.

Gestión de varios proveedores

Puedes guardar varias conexiones LLM (distintos proveedores o claves) y cambiar cuando quieras:

/providers           # lista todos; ▶ es el activo
/use 2               # cambiar por número (o /use <id>)
/rm 3                # eliminar un proveedor

Añade proveedores con /connect. El cambio se aplica al instante, sin reiniciar.

Subcomandos de línea de comandos

Además de entrar en la sesión interactiva con zqagent, la CLI tiene cuatro subcomandos:

zqagent serve [--port <n>] [--host <addr>] [--data-dir <dir>]   # servicio residente sin interfaz
zqagent link --hub <url> --username <correo/teléfono> --password '<contraseña>'  # conexión por cuenta (sin reiniciar)
zqagent link --hub <url> --code <código>                         # conexión con código de un solo uso (sin reiniciar)
zqagent rename <nombre>                                          # cambiar el nombre del nodo en el Hub
zqagent update [--status|--check|--now|--rollback]               # ver/ejecutar la autoactualización y el rollback

zqagent también admite --resume <id-conversación> para restaurar la anterior y --debug para emitir el registro de diagnóstico de arranque.

serve también puede conectarse al arrancar: --hub <url> --enroll-code <código> --label <nombre>, o con cuenta: --hub <url> --username <correo/teléfono> --password <contraseña>.

En el archivo único de Windows cambia zqagent por zqagent.exe (si no está en PATH, usa .\zqagent.exe):

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"
zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <contraseña>
zqagent.exe link --hub https://hub.cd-zq.com --code <código>

zqagent link sin credenciales entra en un asistente interactivo; la contraseña también puede darse con ZQAGENT_HUB_PASSWORD.

En Windows, link también detecta automáticamente el servicio de nodo instalado por la app de escritorio, así que normalmente no hace falta --data-dir; solo hay que indicarlo si configuraste una tarea programada manual y el directorio de datos no está en la ubicación predeterminada.

Consulta Iniciar el nodo.

Diagnóstico de arranque (--debug)

Ante problemas como «se cierra al arrancar y la consola no muestra nada», activa el diagnóstico con --debug:

zqagent --debug              # ejecutable único (macOS / Linux)
node bin/zqagent --debug     # entrada instalada por npm

zqagent.exe --debug          :: archivo único de Windows
set ZQAGENT_DEBUG=1          :: cmd de Windows, forma equivalente

export ZQAGENT_DEBUG=1       # bash/zsh

El registro de diagnóstico se escribe en disco de forma síncrona (sin pasar por el búfer de stdout, así que no se pierde si el proceso se cae o sale de inmediato) y también se muestra por stderr. La ruta se resuelve en este orden:

Variable	Significado
ZQAGENT_DEBUG_LOG	Ruta completa del archivo de registro (prioritaria)
ZQAGENT_DEBUG_DIR	Directorio de registros; el archivo se llama siempre zqagent-debug.log
Ninguna definida	zqagent-debug.log en el directorio temporal del sistema (os.tmpdir())

El registro incluye una instantánea del entorno, las fases del arranque y la pila del fallo (las credenciales como OPENAI_API_KEY solo se registran como «definida o no + longitud», nunca en claro). La línea donde se detiene el registro es el punto de fallo. Al quitar --debug se desactiva por completo: no escribe archivos ni registra manejadores.

Sondas de control: determinar en qué capa está el problema

El artefacto de archivo único = base oficial de node + blob SEA inyectado + el código de negocio. Cuando se cierra al arrancar, separar las tres capas con muestras mínimas es mucho más rápido que adivinar en el código:

Muestra	Cómo se genera	Qué significa si no arranca
_node-base-<ver>-<platform>-<arch>	node oficial, sin cambios	Bloqueo en el sistema, antivirus o cargador; no tiene que ver con el empaquetado
_sea-minimal-probe-<platform>-<arch>	sonda SEA mínima, useCodeCache: false	Fallo de inyección o carga del SEA (mira el código de salida, p. ej. 0xC0000005)
_sea-cc-probe-<platform>-<arch>	igual pero useCodeCache: true	La compilación cruzada incluye la caché de código V8 de la máquina de compilación
zqagent-windows-x64.exe	artefacto real	Si las tres anteriores funcionan, el problema está en la inicialización del código; sigue con --debug

pnpm run probes:sea                                   # win32-x64 (predeterminado)
pnpm run probes:sea -- --arch arm64                   # win32-arm64
pnpm run probes:sea -- --platform linux --arch x64    # genera la sonda linux en Linux (ejecutable local)
pnpm run probes:sea -- --platform darwin --arch arm64 # genera la sonda macos en macOS (ejecutable local)

Además de stdout, las sondas escriben zqagent-probe.log en el directorio temporal; aunque «la consola no muestre salida», el registro en disco demuestra si el JS se ejecutó.

El sha256 del artefacto inyectado cambia en cada compilación (el blob guarda la ruta absoluta del script main en la máquina de compilación), así que usa solo el hash de la base _node-base-* como prueba de «archivo íntegro/coherente».

Notas para macOS: SEA requiere Node ≥ 20; el artefacto darwin necesita codesign --remove-signature antes de inyectar y codesign --sign - --force después para una firma temporal (el script lo hace al generar la sonda en local); el kernel arm64 rechaza binarios sin firmar. Generar artefactos para Windows es un ensamblado cruzado puro (postject solo escribe archivos, no ejecuta), así que puedes producir el .exe desde macOS/Linux.

En Windows, coloca todo el conjunto en un directorio y ejecuta release/cli/diagnose.cmd: ejecuta node -e, las dos sondas y zqagent --debug, muestra el código de salida de cada muestra, el registro de diagnóstico y el registro en disco de las sondas; basta copiar toda la pantalla para localizarlo.

Siguiente paso

• Herramientas integradas
• Mecanismo de Agent
• MCP y gestión de herramientas