Referencia Completa del CLI
Guía detallada de sintaxis, argumentos, banderas y códigos de retorno de todos los comandos y subcomandos de gz-ia.
Tabla Resumen de Comandos
| Comando / Subcomando | Argumentos / Flags | Nivel de Permiso | Descripción |
|---|---|---|---|
gz-ia | N/A | Heredado | Lanza la interfaz gráfica de terminal (TUI) por defecto. |
gz-ia start | N/A | Heredado | Inicia la TUI interactiva con estética Fastfetch y menús. |
gz-ia chat | -p, --provider-m, --perm-i, --prompt-d, --dir | readonlysupervisedautonomous | Inicia una sesión directa conectada al agente de IA seleccionado. |
gz-ia session list | -d, --dir | N/A | Lista en formato tabular todas las sesiones del proyecto. |
gz-ia session show | <id>-d, --dir | N/A | Muestra la metadata detallada y estado de una sesión. |
gz-ia session kill | <id>-d, --dir | N/A | Termina de forma controlada el proceso de una sesión (SIGTERM + SIGKILL). |
gz-ia session resume | <id>-d, --dir | Heredado de la sesión | Reanuda una sesión previa invocando al agente nativo (--continue/--resume). |
gz-ia session delete | <id>-d, --dir | N/A | Elimina el registro persistente y destruye el worktree y la rama asociada. |
gz-ia session path | <id>-d, --dir | N/A | Imprime en stdout la ruta absoluta del espacio de trabajo. |
gz-ia session diff | <id>--stat-d, --dir | N/A | Muestra las diferencias de código producidas en la sesión. |
gz-ia session read | <id>--stat-d, --dir | N/A | Inspecciona el contenido y diff actual del worktree sin mutar el base. |
gz-ia session merge | <id>--squash--no-commit-d, --dir | N/A | Integra los cambios del worktree a la rama principal de trabajo. |
gz-ia session get | <id>--squash--no-commit-d, --dir | N/A | Trae e integra las modificaciones producidas en el worktree hacia el directorio activo. |
gz-ia session metrics | <id>--json--detailed-d, --dir | N/A | Calcula duración, pasos, desglose de tokens y uso de herramientas. |
gz-ia session log | <id>-a, --action-s, --stage--status--agent-r, --role--duration--error-d, --dir | N/A | Registra un evento estructurado en .events.jsonl. |
gz-ia session logs | <id>-f, --follow--json-d, --dir | N/A | Consulta histórica o transmisión en vivo de los eventos de una sesión. |
gz-ia update | -c, --check-f, --force--version--install-dir | N/A | Verifica e instala la última versión de gz-ia desde Nexus/Forgejo. |
gz-ia version | N/A | N/A | Muestra la versión, commit SHA y fecha de compilación. |
Detalle de Comandos
gz-ia / gz-ia start
Inicia la interfaz de usuario de terminal (TUI interactiva).
gz-ia
# o
gz-ia startgz-ia chat
Lanza una sesión de terminal conectada a un agente de IA.
gz-ia chat [flags]Banderas (Flags):
-p, --provider <id>: Proveedor agéntico (agy,claude,opencode,pi-agent). Predeterminado: primer agente instalado disponible.-m, --perm <nivel>: Nivel de permiso (readonly,supervised,autonomous). Predeterminado:supervised.-i, --prompt <texto>: Prompt inicial inyectado al agente de IA.-d, --dir <ruta>: Directorio de trabajo base (predeterminado: directorio actual).
Ejemplos:
# Chat supervisado estándar
gz-ia chat -p agy
# Chat autónomo con prompt directo
gz-ia chat -p claude -m autonomous -i "Refactorizar internal/logger"gz-ia session list
Lista en formato tabular todas las sesiones agénticas del proyecto.
gz-ia session list [-d <ruta>]gz-ia session show
Muestra la metadata en detalle de una sesión específica.
gz-ia session show <session-id> [-d <ruta>]gz-ia session kill
Detiene forzosamente el proceso del agente de la sesión.
gz-ia session kill <session-id> [-d <ruta>]Envía SIGTERM y escala a SIGKILL si no finaliza dentro del tiempo de espera.
gz-ia session resume (alias: continue)
Reanuda una sesión existente, reingresando a su worktree y reconectando la terminal interactiva con la bandera de reanudación adecuada del agente (--continue o --resume).
gz-ia session resume <session-id>
gz-ia session continue <session-id>gz-ia session delete (alias: rm)
Elimina el registro de la sesión y destruye el Git Worktree efímero y la rama de Git correspondiente.
gz-ia session delete <session-id>
gz-ia session rm <session-id>gz-ia session path
Imprime únicamente la ruta absoluta del directorio de trabajo de la sesión.
gz-ia session path <session-id>gz-ia session diff
Muestra las diferencias Git acumuladas en la sesión.
gz-ia session diff <session-id> [--stat]gz-ia session read
Inspecciona el contenido y diff actual de la sesión de manera estructurada (compatible con herramientas agénticas).
gz-ia session read <session-id> [--stat]gz-ia session get (alias: merge)
Fusiona e integra los cambios del worktree hacia la rama de trabajo activa.
gz-ia session get <session-id> [--squash] [--no-commit]Banderas:
--squash: Condensa todos los commits intermedios de la sesión en un solo commit.--no-commit: Fusiona los archivos y los deja en el staging area de Git sin crear commit automático.
Semántica técnica de integración:
- Si hay cambios pendientes en el worktree de la sesión, genera un commit de seguridad en la rama
harness/<id>. - Ejecuta un
git merge(ogit merge --squashcon--squash, y sin commit si se pasa--no-commit) de la ramaharness/<id>en la rama activa del repositorio. - Si la rama base avanzó y existen conflictos, Git se detiene sin sobreescribir tus archivos; informa los archivos en conflicto y mantiene el worktree intacto para resolución manual (
gz-ia session path <id>) o abortar (git merge --abort).
gz-ia session metrics
Calcula y presenta el reporte de métricas de la sesión.
gz-ia session metrics <session-id> [--json] [--detailed]gz-ia session log
Registra un evento de observabilidad en .harness/sessions/<id>.events.jsonl.
gz-ia session log <session-id> \
-a, --action <texto> \
-s, --stage <READ|PENDING|FINISH> \
--status <OK|FAILED> \
--agent <nombre> \
[-r, --role <rol>] \
[--duration <milisegundos>] \
[--error <mensaje_error>]gz-ia session logs
Visualiza o transmite el flujo de eventos de la sesión.
gz-ia session logs <session-id> [-f, --follow] [--json]gz-ia update
Verifica e instala la última versión binaria disponible desde Nexus / Forgejo.
gz-ia update [flags]Banderas:
-c, --check: Comprueba únicamente si existe una versión más reciente sin descargarla.-f, --force: Fuerza la reinstalación o downgrade a la versión indicada.--version <v>: Especifica la versión exacta a instalar (ej.0.0.2).--install-dir <dir>: Ruta donde se ubicará el binario actualizado.
gz-ia version
Muestra la información de versión del binario compiled.
gz-ia version