9. Comandos esenciales del TUI y del CLI

Objetivo del tema

Dominar la cara "sin interfaz" de OpenCode: ejecutar tareas no interactivas con opencode run, gestionar sesiones y credenciales desde la terminal, levantar servidores locales y preparar scripts o pipelines de automatización.

9.1 Dos caras del mismo agente

Los comandos slash de la TUI (tema 7) cubren el trabajo interactivo diario. Pero OpenCode también funciona como herramienta de línea de comandos clásica: sin interfaz, con entrada y salida por terminal, ideal para scripts, cron jobs y CI/CD.

opencode                      # abre la TUI (comportamiento por defecto)
opencode run "mensaje"        # ejecuta una tarea y termina
opencode serve                # servidor HTTP sin interfaz

9.2 opencode run: tareas no interactivas

El subcomando run envía un mensaje al agente, deja que trabaje y muestra el resultado:

opencode run "Explica cómo se maneja la autenticación en este proyecto"
opencode run --model anthropic/claude-sonnet-4 "Revisa el archivo server.ts"
opencode run --agent plan "Propone un plan de refactor para utils/"

Banderas útiles de opencode run

Bandera	Función
--model / -m	Fija el modelo en formato proveedor/modelo para esta ejecución.
--agent	Ejecuta con un agente concreto (por ejemplo plan) en lugar de Build.
-c / --continue	Continúa la última sesión en lugar de crear una nueva.
-s / --session	Retoma una sesión específica por su ID (combinable con --fork para bifurcarla).
-f / --file	Adjunta archivos al mensaje.
--format json	Devuelve los eventos en JSON crudo: perfecto para procesarlos desde scripts.
--title	Nombra la sesión generada para encontrarla después.
--attach URL	Se conecta a un servidor serve activo, evitando arranques en frío repetidos.

9.3 Sesiones y estadísticas desde la terminal

Todo lo que haces en la TUI queda registrado y se administra por comandos:

opencode session list              # lista sesiones (acepta --format json)
opencode session delete <id>       # elimina una sesión
opencode stats                     # consumo de tokens y costos
opencode stats --days 7            # sólo los últimos 7 días

El comando stats es muy útil para controlar el gasto: muestra tokens usados, sesiones, herramientas invocadas y desglose por modelo (--models) o proyecto (--project).

9.4 Credenciales y catálogo de modelos

Sin necesidad de abrir la TUI puedes gestionar proveedores:

opencode auth login                # configura claves de cualquier proveedor
opencode auth list                 # proveedores autenticados
opencode auth logout               # cierra la sesión de un proveedor
opencode models                    # lista modelos disponibles (proveedor/modelo)
opencode models anthropic          # filtra por proveedor
opencode models --refresh          # actualiza el caché desde models.dev

opencode models es la referencia definitiva para saber el identificador exacto que debes escribir en la configuración.

9.5 Servidores: serve, web y attach

# Terminal 1: backend con acceso web
opencode web --port 4096 --hostname 0.0.0.0
# Terminal 2: TUI conectada a ese backend
opencode attach http://10.20.30.40:4096

9.6 Utilidades de mantenimiento e integración

Otros comandos del CLI que conviene conocer

Comando	Función
opencode upgrade [versión]	Actualiza a la última versión o a una específica.
opencode uninstall	Desinstala y limpia archivos; admite --dry-run para previsualizar.
opencode export [sesión]	Exporta una sesión a JSON (con opción de sanitizar datos sensibles).
opencode import archivo|URL	Importa sesiones desde JSON o desde un enlace público share.
opencode agent create	Asistente guiado para crear agentes personalizados (tema 14).
opencode mcp add / list / auth	Gestiona servidores MCP y su OAuth (tema 15).
opencode github install	Instala el agente de GitHub en tu repositorio (tema 13).
opencode pr <número>	Descarga un pull request de GitHub, hace checkout y abre OpenCode sobre él.
opencode plugin <módulo>	Instala plugins actualizando la configuración automáticamente.

9.7 Variables de entorno útiles

Variables más usadas al operar OpenCode por script

Variable	Efecto
OPENCODE_CONFIG	Ruta alternativa al archivo de configuración principal.
OPENCODE_PERMISSION	Inyecta permisos en JSON sin editar archivos.
OPENCODE_SERVER_PASSWORD	Habilita autenticación básica en serve/web.
OPENCODE_DISABLE_AUTOUPDATE	Evita comprobaciones automáticas de actualización (ideal en CI).
OPENCODE_DISABLE_AUTOCOMPACT	Desactiva la compactación automática de contexto.
OPENCODE_AUTO_SHARE	Comparte sesiones automáticamente (usar con criterio).

9.8 Ejemplo práctico: revisión diaria automatizada

Un script sencillo que deja un informe del estado del repositorio cada mañana:

#!/usr/bin/env bash
set -e

# Revisión con salida estructurada para procesar o archivar
opencode run \
  --title "revisión-diaria" \
  --format json \
  "Analiza git status y los cambios pendientes. Resume riesgos y sugiere próximos pasos." \
  > informes/$(date +%F).json

echo "Informe generado en informes/$(date +%F).json"

En un entorno de CI conviene combinar --auto (aprueba permisos no denegados explícitamente) con políticas restrictivas definidas en el proyecto, tal como veremos en los temas de personalización y seguridad.

Conclusión: el modo CLI transforma a OpenCode de asistente interactivo a componente programable: tareas puntuales con run, auditoría de uso con stats, servidores compartidos con serve/web y mantenimiento con upgrade. Con estas piezas estamos listos para el primer proyecto práctico completo con Node.js y Express.