CLI de Thulu

El comando thulu instala y mantiene una instalación self-hosted. Casi todo lo del día a día se hace en el dashboard; la CLI queda para lo que no puede pasar por HTTP (crear el primer workspace o la primera key), lo que cambia la instalación (actualizar, limpiar, desinstalar), mover datos entre instalaciones y el runner. thulu help lista todo. Los mensajes salen en castellano si tu terminal está en castellano, o con OCTOPUS_LOCALE=es.

El thulu que baja install.sh trae sólo los comandos para tu máquina: el servidor vive en la imagen octopus, y thulu serve desde el binario descargado avisa y sale. Dentro del contenedor del daemon el binario es /app/octopus (./octopus desde su carpeta de trabajo).

Qué necesita cada comando

Los comandos se agrupan por lo que tocan, y de eso depende desde dónde se corren.

Toca	Comandos	Necesita
La instalación (archivos de deploy/)	init, open, update, apply, gc, uninstall	Correrlo desde la carpeta de la instalación o una de adentro, o tener la instalación en ~/.octopus (OCTOPUS_HOME). Se puede forzar con -root.
El daemon por HTTP	status, ps, logs, stop	Que el daemon responda en OCTOPUS_URL (por defecto http://localhost:8585) y una credencial: una API key del workspace en OCTOPUS_API_KEY, o el token de dev de la instalación.
La base directo	workspace, keys, agents	La base que nombra deploy/.env, vista desde tu máquina (con el Postgres del stack, localhost:5433). OCTOPUS_DATABASE_URL en el entorno tiene prioridad.
El contenedor del daemon	export, import	Que el stack esté corriendo. El comando entra solo al contenedor (docker compose exec, o kubectl exec en Kubernetes), donde están la base y los adjuntos; el archivo viaja por la entrada y la salida estándar.
La máquina de una persona	runner	Ver Runner.
Nada	mirror, version, help

Nota

El Postgres del stack de compose sólo escucha en 127.0.0.1:5433. Si los comandos de datos no llegan a la base (otra máquina, una base externa sin acceso desde el host), corrélos adentro del contenedor del daemon, donde OCTOPUS_DATABASE_URL ya está puesta: docker compose -f deploy/docker-compose.standalone.yml exec octopus ./octopus keys workspaces. En Kubernetes, kubectl exec deploy/<release>-octopus -- /app/octopus ….

Instalar y entrar

Comando	Qué hace
thulu init	El asistente de instalación, con formularios en la terminal: pregunta, escribe deploy/.env o los values de Helm, crea el workspace y la key de operador y levanta el stack. -dry-run pregunta todo sin escribir; -non-interactive toma los defaults o las respuestas de la corrida anterior; -plain usa preguntas numeradas en texto plano; -stack <archivo> corre un stack sin preguntar el modo. Detalle en Instalación self-hosted.
thulu open	Imprime la dirección del dashboard y abre el navegador. En una instalación sin login agrega el token de dev al link, que el daemon cambia por una cookie de 30 días. Si no hay navegador, deja el link para pegar.
thulu version	La versión del binario (dev en un build local).

Lo que ve quien entra a una instalación sin login sin pasar por thulu open.

Workspaces y API keys

Toda key pertenece a un workspace, y en una instalación vacía no hay con qué pedir una por HTTP. Estos comandos son la puerta de entrada desde el host. Las keys de todos los días se emiten en Configuración → “API” (ver Seguridad y auditoría).

Comando	Qué hace
thulu workspace create -name … -slug … -owner-email <email>	Crea un workspace y su dueño (el usuario se crea si no existe). Los tres flags son obligatorios. Si el slug ya existe, imprime su id con “(ya existía)” y no cambia nada.
thulu workspace list	Lista id, nombre y slug de cada workspace. thulu keys workspaces es un alias.
thulu keys mint -permissions <lista o preset>	Emite una key y la imprime una sola vez en JSON. Opcionales: -workspace (id o slug; con un solo workspace se puede omitir), -name (por defecto “key de operador”), -role (viewer, developer, admin, owner; por defecto developer), -expires-in-days.

Emitir una key desde el host

1. Desde la carpeta de la instalación, emití la key con un preset de permisos (read-only, ci, agent o full) o una lista separada por coma:

   $ thulu keys mint -workspace acme -name "CI de acme" -permissions ci -expires-in-days 90
   {
     "expires_at": "2027-01-14T15:10:16.621690168Z",
     "id": "e1be935dfa2f97e5",
     "key": "oct_6b77…",
     "name": "CI de acme",
     "permissions": ["tasks:read", "tasks:write", "projects:read", "runs:read"],
     "prefix": "oct_6b779c0e",
     "role": "developer",
     "workspace_id": "5c2e172105550469"
   }

2. Copiá el valor de key: sólo se guarda su hash. La key aparece después en Configuración → “API” con su prefijo, y se revoca desde ahí.

Precaución

-expires-in-days 0 (o no pasarlo) significa “el máximo de la instalación”: OCTOPUS_API_KEY_MAX_TTL, 90 días por defecto. keys mint toma ese máximo de deploy/.env si no está en tu entorno. Un pedido de más días que el máximo se rechaza. La key de operador que emite thulu init sigue la misma regla.

Agentes en ejecución

Estos tres comandos miran los contenedores (o pods) de agentes que están corriendo ahora, no las definiciones de agentes. Para ver las corridas con su historia, usá el dashboard: Corridas de agentes.

Comando	Qué hace
thulu status (o ps)	Tabla con NOMBRE, TIPO, PROYECTO, ESTADO, ACTIVO e ID de cada agente corriendo. Sin ninguno: “No hay agentes en ejecución.”
thulu logs <agente> [-f]	Las últimas 100 líneas de log del agente; -f las sigue. Acepta el nombre o el id del contenedor.
thulu stop <agente>	Borra el contenedor del agente (en Kubernetes, el pod). Necesita rol admin.

Mover datos entre instalaciones

thulu export escribe un workspace en un .tar.gz: tableros, tareas con adjuntos, proyectos (con el script de inicialización vigente y el repositorio de los proyectos subidos), entornos, dashboards y métricas, más la capa global (agentes, skills, configuración y MCP registrados). thulu import lo reproduce en otra instalación con los mismos ids, en orden de dependencias, y se puede repetir para completar una restauración a medias. Los secretos nunca viajan: el import lista cuáles hay que volver a cargar.

Los dos corren dentro del contenedor del daemon de la instalación donde los llamás: el comando entra solo con docker compose exec o kubectl exec, y el archivo vuelve a tu máquina.

1. En la instalación de origen, desde su carpeta. -workspace acepta el id o el slug, y con un solo workspace se puede omitir:

   $ thulu export -workspace acme -out acme.tgz

2. Copiá acme.tgz a la máquina de destino.

3. En la instalación de destino:

   $ thulu import acme.tgz

   Por defecto el import usa el workspace del bundle, que tiene que existir en el destino; -workspace <id o slug> lo mete en otro. La configuración de la instalación de origen se aplica sólo con -with-settings, porque alcanza a todos los workspaces del destino. -json imprime los conteos en JSON en vez del resumen.

4. Cargá a mano los secretos que lista la salida (tokens de git, keys del modelo, credenciales de nube) y revisá cada advertencia.

Para mover sólo las definiciones de agentes hay comandos aparte:

Comando	Qué hace
thulu agents export [-workspace <id o slug>]	Escribe los agentes de un workspace como un pack JSON en la salida estándar.
thulu agents import <dir|pack.json> [-workspace <id o slug>] [-templates]	Importa agentes desde una carpeta de definiciones o un pack. -templates los marca como plantillas para clonar.
thulu agents verify <dir> [-workspace <id o slug>]	Comprueba que la base reproduce exactamente esa carpeta, antes de borrarla.
thulu agents gc [-keep N]	Recorta el historial de revisiones de cada archivo de agente y libera el contenido que ya no se usa.

Con un solo workspace, -workspace se puede omitir. Para pasar un agente o una skill de a uno, el Workshop exporta e importa JSON desde el dashboard.

Actualizar

Thulu nunca se actualiza solo. Configuración → “Actualizaciones” muestra la versión en marcha, las disponibles y el comando exacto para cada una; los comandos se corren en la máquina que administra la instalación. Detalle del proceso en Operación self-hosted.

Comando	Qué hace
thulu update -check	Muestra el paquete de cambio de la versión más nueva permitida, o de -version X, sin cambiar nada: imágenes, migraciones, variables que faltan, pasos manuales y plan de vuelta atrás. -o cambio.md (o .json) lo guarda en un archivo.
thulu update -version X	Instala esa versión (sin -version, la más nueva permitida): verifica el manifiesto firmado, toma un snapshot de la base, baja cada imagen por su digest, recrea el stack y espera a que el daemon responda con la versión nueva. Si algo falla después del cambio, vuelve sola a la anterior.
thulu apply	Lleva la instalación a la versión que dice deploy/.env (OCTOPUS_VERSION) o los values de Helm. Mismos flags que update.
thulu update -rollback	Vuelve a la versión anterior.
thulu update -to X [-restore <snapshot>]	Vuelve a una versión guardada. Si no es el rollback_to de la versión actual, necesita restaurar el snapshot de la base (los datos posteriores se pierden), o -restore external si restauraste vos una base externa.
thulu update -kept	Lista las versiones guardadas y el comando para volver a cada una. -keep X fija una para que no se borre; -unkeep X la libera.
thulu mirror <versión> -to <registry> -dir <carpeta>	Copia una versión para una instalación sin internet: imágenes con sus firmas, el chart y los archivos firmados.

Flags compartidos por update y apply: -yes (no pide confirmación), -ack-manual-steps (confirma los pasos manuales de la versión), -backup-confirmed (obligatorio con base externa: confirma que hiciste tu propio backup), -registry y -chart-registry (bajar de un mirror), -api-key-file (la key con la que se informa el resultado al log de auditoría; nunca como valor en la línea de comandos), -no-fetch-cli.

Limpiar y desinstalar

Los dos son dry-run por defecto: muestran qué harían y terminan con el comando para hacerlo de verdad. Sólo tocan objetos de Thulu; los contenedores, imágenes y volúmenes de otros proyectos del host no se listan.

Comando	Qué hace
thulu gc	Lista lo que Thulu dejó y ya no hace falta: contenedores de agente, sandbox y chat parados hace más de -min-age (1 hora por defecto), imágenes viejas, cachés, redes y snapshots más allá de los 5 más nuevos. -apply lo borra. -unclaimed suma imágenes de Thulu que ninguna versión configurada reclama. Los volúmenes de datos nunca se tocan.
thulu uninstall	Muestra qué borraría: el servicio del runner si lo instalaste, el stack (docker compose down), cada contenedor e imagen de Thulu (incluida la de rollback), la red de agentes, los volúmenes de sesión personal de Claude y la configuración. -yes lo hace. La base, los worktrees, deploy/.env, los backups y la carpeta de trabajo del runner se quedan salvo con -purge-data. En Kubernetes no borra nada: imprime los comandos de helm y kubectl para que los corras vos. El binario no se borra; al final se muestra su ruta.

Peligro

thulu uninstall -yes -purge-data borra la base, cada worktree de proyecto, los certificados, deploy/.env (con la contraseña de la base y la clave de las credenciales) y todos los snapshots. No hay vuelta atrás. Si vas a necesitar algo, corré antes thulu export.

Runner: agentes en tu máquina

Un runner corre las corridas de los proyectos asociados en la máquina de una persona, con su git, sus herramientas, sus MCP y su login de claude. Sólo funciona con Claude Code. Viene prendido en Docker y apagado en Kubernetes (OCTOPUS_RUNNERS), donde no se probó. No tiene pantalla en el dashboard: el alta es por API y CLI.

Comando	Qué hace
thulu runner register -url <daemon> -token <token>	Cambia un token de un solo uso (lo emite un admin con POST /runners/tokens) por la credencial del runner y la guarda en la config local.
thulu runner add-project <id del proyecto> <carpeta>	Asocia un proyecto de runner al checkout de esa carpeta.
thulu runner run	Toma y corre las corridas. Sólo hace pedidos salientes al daemon, así que sirve contra un daemon remoto por HTTPS.
thulu runner service install|uninstall|status	El runner como agente de launchd en macOS o unidad de systemd de usuario en Linux, con su log en ~/.octopus/runner.log.

En proyectos de runner no hay chat de tarea, mensajes en vivo ni argus-sandbox, y todos los proyectos de una tarea tienen que estar en el mismo runner. thulu init ofrece configurarlo en una instalación Docker.

El daemon

thulu serve arranca el daemon, y sólo lo trae la imagen octopus. En una instalación con compose o Helm lo arranca el contenedor; a mano sólo hace falta para desarrollo.

Flag	Por defecto	Qué es
-addr	:8585	Dirección de escucha.
-data	<agents-dir>/octopus/data	Directorio de datos: worktrees de proyectos, logs y adjuntos.
-agents-dir	La carpeta del binario si tiene agents/, si no la de arriba	Directorio base. Las definiciones de agentes viven en Postgres, no acá.

Necesita OCTOPUS_DATABASE_URL. No hay base embebida.

Variables de entorno de la CLI

Variable	Para qué
OCTOPUS_URL	Dirección del daemon para status, logs, stop, open y runner register. Por defecto http://localhost:8585.
OCTOPUS_API_KEY	Una API key del workspace para hablar con el daemon. Sin ella, la CLI usa el token de dev de una instalación sin login.
OCTOPUS_DATABASE_URL	DSN de Postgres para workspace, keys y agents. Sin ella, la CLI usa la base que nombra deploy/.env.
OCTOPUS_HOME	Dónde vive una instalación hecha desde el binario. Por defecto ~/.octopus.
OCTOPUS_LOCALE	Idioma de los mensajes (es o en). Si no está, se usa el de la terminal.

Relacionado

Instalación self-hostedthulu init paso a paso y el primer acceso.

Operación self-hostedActualizaciones, backups y limpieza en detalle.

Seguridad y auditoríaAPI keys desde el dashboard y el log de auditoría.

Workspaces y equipoInvitar miembros y manejar roles.