Referencia de comandos

Ejecuta zeltro --help para ver esta misma lista en tu terminal, o zeltro <command> --help para un solo comando.

Los comandos marcados con (directorio del proyecto) deben ejecutarse desde dentro de un directorio de proyecto.

🛠️ Herramientas de desarrollo#

Se ejecutan desde el directorio del proyecto

✅ Análisis estático y linting#

Se ejecutan desde el directorio del proyecto; las rutas son relativas a la raíz del proyecto (por ejemplo app/Console/Commands/Foo.php)

📦 Ejecución en el contenedor#

Se ejecutan desde el directorio del proyecto

⚡ Comandos ampliados de Laravel#

Se ejecutan desde el directorio del proyecto

🐍 Comandos ampliados de Django#

Se ejecutan desde el directorio del proyecto

🔧 Gestión de servicios#

Se ejecutan desde cualquier lugar

🎛️ Gestión de procesos#

Se ejecutan desde el directorio del proyecto

📁 Gestión de proyectos#

zeltro status imprime direcciones que puedes abrir desde el host: http://<container-ip> en local (o http://localhost:<port> en macOS) y http://<host-lan-ip>:<port> desde la LAN. http://<project>/ no funciona desde el host: los nombres de proyecto solo se resuelven dentro de los contenedores. No existe zeltro ps.

⚙️ Gestión del sistema#

Servicios compartidos opcionales

Solo Redis, Memcached y MailHog están siempre en ejecución. Todo lo demás está apagado hasta que lo actives, y la lista de servicios activados se guarda en OPTIONAL_SERVICES en /etc/zeltro-cli/.env. zeltro new, zeltro setup y zeltro install activan automáticamente la base de datos que necesita un proyecto.

zeltro enable-service minio
zeltro disable-service minio
zeltro enable-service --json-output     # no name: list every optional service and its state

Un servicio solo queda registrado como activado si arranca y sigue en ejecución. En un equipo instalado antes del cambio de nombre a Zeltro, ejecuta zeltro migrate-names para pasar los contenedores a los nombres zeltro-*.

Mensajes entre sesiones de agentes

Cuando la app de Zeltro aloja sesiones de agentes en varios proyectos (en uno o en varios hosts), pueden enviarse mensajes entre sí. La app se encarga del enrutamiento mediante una cola por usuario en ~/.zeltro/bus/: publica peers.json, y send deja un archivo JSON por mensaje en outbox/.

zeltro peers                                   # list live sessions as project@host; marks yours
zeltro peers --json-output
zeltro send blog -- "API schema changed"       # one target
zeltro send blog api@shop -- "Rebuild please"  # several targets
zeltro send --all -- "Heading out"             # every live session except you
git diff | zeltro send api -- -                # read the message from stdin

• Ejecuta send desde dentro del directorio de tu proyecto; así es como se te identifica.
• Un project a secas funciona cuando solo hay una sesión activa con ese nombre; si no, usa project@host.
• Todos los destinatarios tienen que ser sesiones activas o no se envía nada. Los mensajes tienen un límite de 16 KB.
• Con un solo destinatario, el -- es opcional: zeltro send blog "message".
• Salir con 0 significa que el mensaje quedó en cola. Llega a la terminal del destinatario como [Zeltro message from <you>@<host> to <targets>] ....

Pedirle cosas a la app de Zeltro

Un agente en una sesión que inició la app de Zeltro puede usar la ventana de la app para comunicarse con el usuario:

zeltro gui notify --level info "Admin login" "http://shop/admin  user: admin  password: ..."
zeltro gui notify --level success "Pricing page added" "Open /pricing to see it"
zeltro gui secret STRIPE_KEY --reason "for checkout"   # writes it into .env; never printed
zeltro gui notify --level warning "Tests failing" "3 failures in api/"
zeltro gui open --project                               # or: zeltro gui open https://...
zeltro gui settings ai --reason "add an OpenRouter key"

Códigos de salida: 0 correcto, 1 error, 2 uso incorrecto, 3 la app no está disponible (pregunta en el chat), 4 se agotó el tiempo, 5 el usuario lo rechazó, 6 la app se negó. secret solo escribe en archivos dentro del proyecto.

zeltro ai y zeltro resume también le avisan a la app cuando termina cada turno, usando zeltro gui event como hook para Claude Code, Codex y aider. Las opciones del hook solo duran esa ejecución y no cambian tus archivos de configuración, y el de Codex se omite si ya definiste tu propio notify.

Opciones de zeltro ai-set

zeltro ai-set gestiona la CLI del agente de IA global, el modelo y la clave de API que usa Zeltro.

zeltro ai-set --agent claude --model opus
zeltro ai-set --agent codex --model gpt-6-sol
zeltro ai-set --agent aider --model anthropic/claude-sonnet-5 --api-key sk-ant-...
zeltro ai-set --install-only --agent qwen
zeltro ai-set --json-output

Opciones admitidas:

• --agent <name>: define la CLI del agente de IA (codex, claude, agy, qwen, aider, opencode o hermes). gemini sigue funcionando, pero está obsoleto: Google dejó de ofrecer Gemini CLI a las cuentas personales el 2026-06-18, así que usa agy, la Antigravity CLI que lo reemplaza.
• --model <name>: define el nombre del modelo (opcional para Codex, Claude, agy, Gemini, OpenCode y Hermes; obligatorio para Qwen y Aider, y para OpenCode y Hermes con --api-base). OpenCode y Hermes usan provider/model, por ejemplo openai/gpt-5.4-mini.
• --api-key <key>: define la clave de API de la IA (opcional para Codex, Claude, agy, OpenCode y Hermes; para agy y Gemini es una clave de API de Gemini, que se pasa como GEMINI_API_KEY; obligatoria para Aider). --api-key "" borra una clave guardada.
• --api-base <url>: define un endpoint de API personalizado: compatible con OpenAI para Codex, Qwen, Aider, OpenCode y Hermes; un proxy compatible con Anthropic para Claude. --api-base none lo borra.
• --allow-unattended / --no-allow-unattended: permite que el agente trabaje sin pedir aprobación, o lo desactiva. Se escribe en la configuración propia del agente; si omites las dos, no cambia. Es lo que siguen las ejecuciones en la terminal; en la app de escritorio, el interruptor "Trabaja sin preguntar" de cada proyecto (activado de forma predeterminada) lo reemplaza en cada sesión mediante ZELTRO_AI_UNATTENDED.
• --install-only: junto con --agent, instala la CLI de ese agente si falta, sin convertirlo en el predeterminado. No escribe nada en la configuración de Zeltro.
• --json-output: devuelve el resultado como JSON (no interactivo). Por sí solo, zeltro ai-set --json-output es una consulta de solo lectura: no instala ni escribe nada, e informa de los ajustes actuales más "session_overrides": true, "ai_language": true y "installed_agents": [...].

Cambiar --agent sin --model ni --api-base borra el modelo y el endpoint anteriores.

Ejemplos:

• Ver los ajustes de IA actuales:
  • zeltro ai-set --json-output
• Configurar Codex con un modelo:
  • zeltro ai-set --agent codex --model gpt-6-sol
• Configurar Claude con un modelo:
  • zeltro ai-set --agent claude --model opus
• Configurar Aider con Anthropic:
  • zeltro ai-set --agent aider --model anthropic/claude-sonnet-5 --api-key sk-ant-...
• Configurar Aider con un servidor local de Ollama:
  • zeltro ai-set --agent aider --model openai/llama3.1 --api-key ollama --api-base http://localhost:11434/v1

Ajustes de IA por sesión

zeltro ai, resume, create (incluido --classify-only), clone, create-installer y update-installer usan el agente definido con zeltro ai-set. Para usar otro en una sola ejecución, define estas variables de entorno. Nunca se escriben en /etc/zeltro-cli/.env.

Sin definir significa "usa el valor de ai-set"; definida pero vacía significa "bórralo para esta ejecución". Un agente desconocido, un archivo de clave ilegible o un agente de reemplazo que no está instalado dan error antes de que se ejecute nada, y no se instala nada: usa primero zeltro ai-set --install-only --agent <name>.

ZELTRO_AI_AGENT=qwen ZELTRO_AI_MODEL=qwen/qwen3-coder-30b-a3b-instruct \
  ZELTRO_AI_API_BASE=https://openrouter.ai/api/v1 ZELTRO_AI_API_KEY_FILE=~/.or-key \
  zeltro ai "Add a health-check endpoint at /ping"

Aider

Aider es el único agente compatible que no tiene inicio de sesión propio: siempre habla directamente con la API de un proveedor, así que necesita un modelo y una clave.

• El nombre del modelo elige el proveedor: openai/gpt-6-sol, anthropic/claude-sonnet-5, gemini/gemini-2.5-pro, deepseek/deepseek-chat. Consulta la lista de modelos de aider.
• Aider etiqueta las claves por proveedor (--api-key openai=sk-...). Zeltro guarda la clave sola y la etiqueta según el prefijo del modelo, así que con --api-key sk-... basta. Una clave que ya contiene = se pasa tal cual.
• --api-base solo hace falta para un servidor compatible con OpenAI: Ollama, LM Studio, OpenRouter, vLLM. Cuando uses uno, pon openai/ delante del modelo. Déjalo vacío para la API alojada del propio proveedor.
• Zeltro ejecuta Aider con --no-auto-commits, así que sus cambios quedan en tu árbol de trabajo como los de cualquier otro agente, en lugar de confirmarse por ti.

🤖 Creación de proyectos asistida por IA#

zeltro create recoge la idea de tu proyecto, le añade instrucciones propias de Zeltro y entrega la instrucción combinada a la CLI de IA que tengas configurada. Zeltro prepara el entorno. La IA construye la app.

# asks what you want to build (interactive terminals only)
zeltro create

# Pass the idea directly
zeltro create "A timeclock for employees in Django"
zeltro create "A customer check-in system in Laravel"
zeltro create "An inventory tracker in Express"

# Read a long idea from a file or stdin
zeltro create -f big-prompt.md
cat big-prompt.md | zeltro create

# Point to an existing GitHub repo to clone and set it up
zeltro create "https://github.com/monicahq/monica"

Pasa --one-off para detenerte después de la creación y omitir la entrega a la IA.

Lo que hace el agente de IA:

1. Si el framework o el stack no están claros, pregunta cuál usar antes de seguir.
2. Ejecuta zeltro new para crear el proyecto e iniciar sus contenedores.
3. Lee el archivo .env generado para entender la configuración de base de datos, caché y correo.
4. Construye la app con las convenciones propias del framework: migraciones, modelos, seeders, rutas, controladores, plantillas.
5. Actualiza el README del proyecto con la URL local, comandos útiles y las credenciales predeterminadas, si las hay.

Si tu idea coincide con una app conocida que tiene un instalador de Zeltro (Grafana, Gitea, n8n, Portainer, etc.), el agente ejecuta primero zeltro install <name> (la deja en marcha en segundos) y después aplica cualquier personalización adicional de tu instrucción. Nunca tienes que escribir un archivo docker-compose ni saber en qué puerto escucha la app.

La CLI de IA puede estar en la nube o ser local, según tu configuración. Usa zeltro ai-set para elegir qué agente se usa.

Solo clasificar (para interfaces gráficas y otros front ends)

zeltro create --classify-only "<idea>"                  # human-readable
zeltro create --classify-only --json-output "<idea>"    # machine-readable

Ejecuta solo la fase de clasificación: determina el stack, imprime el resultado, sale con 0 y no crea nada. Nunca hace preguntas, así que es seguro llamarlo desde una interfaz gráfica, un script o un agente.

Existe porque el camino no interactivo normal (--one-off, --json-output) toma sin avisar la primera recomendación: está bien para automatizar, pero descarta la elección que una persona habría hecho en el menú. Un front end que quiera presentar esas opciones de forma nativa debe clasificar primero, mostrar los candidatos y luego llamar a zeltro install <app> o zeltro new <framework> <name> con lo que haya elegido el usuario.

El JSON incluye project_name (null cuando la idea no implica un tema concreto, así que conviene preguntar en lugar de rellenarlo), recommended, customization_requested, una database sugerida con su motivo, y candidates: primero las apps y al final el framework, con un máximo de 5. Las apps llevan una única database fija, definida por el instalador; los frameworks llevan un array databases con los motores que admiten. Nunca ofrezcas elegir base de datos para una app. Si falla, emite {"action": "classify", "status": "error", "message": "..."} y sale con un código distinto de cero.

🤖 Sesiones de agentes de IA#

Una vez que hayas definido tu agente de IA global con zeltro ai-set, puedes enviar una instrucción desde cualquier directorio de proyecto de Zeltro:

cd /path/to/project
zeltro ai "Build a unique homepage hero section."

Por defecto, zeltro ai envía una instrucción puntual: el agente la recibe, hace el trabajo y termina. El contexto duradero del proyecto vive en su AGENTS.md (Zeltro lo escribe al crearlo), así que cada instrucción puede ser independiente. Añade --interactive (-i) si prefieres una sesión persistente. --one-off se sigue aceptando por compatibilidad.

zeltro ai --interactive "Add a health-check endpoint at /ping"

zeltro ai:

• Lee AI_AGENT, AI_MODEL, AI_API_KEY y AI_API_BASE de /etc/zeltro-cli/.env, salvo que haya un reemplazo ZELTRO_AI_* definido.
• Ejecuta el agente con la instrucción (las partes entre [...] solo se añaden cuando están definidas):
  • Codex: codex exec [--model "$AI_MODEL"] "<prompt>" (puntual) / codex [--model ...] "<prompt>" (interactivo). La clave va por OPENAI_API_KEY; el endpoint se pasa como -c openai_base_url="…", porque la versión actual de Codex ignora OPENAI_BASE_URL.
  • Claude: claude -p [--model "$AI_MODEL"] "<prompt>" (-p solo en modo puntual). La clave va por ANTHROPIC_API_KEY y el endpoint por ANTHROPIC_BASE_URL.
  • Codex y Claude eliminaron sus opciones --api-key; la clave se pasa por el entorno. Zeltro comprueba que la clave parezca de ese proveedor (sk- para Codex, sk-ant- para Claude) y, si no lo parece, la ignora con una advertencia y deja que la CLI use su propio inicio de sesión: una clave del proveedor equivocado reemplazaría una autenticación que funciona por otra que no puede funcionar.
  • Qwen: qwen --auth-type openai [--model "$AI_MODEL"] --prompt "<prompt>" (puntual) / -i "<prompt>" (interactivo). La clave y el endpoint van por OPENAI_API_KEY / OPENAI_BASE_URL.
  • agy (Antigravity CLI): agy [--model "$AI_MODEL"] --add-dir <projects dir> -p "<prompt>" (puntual) / -i "<prompt>" (interactivo). La clave va por GEMINI_API_KEY, con "modelProvider": "gemini" definido en ~/.gemini/antigravity-cli/settings.json mientras haya una clave guardada; no admite endpoint personalizado.
  • Gemini (obsoleto): gemini [--model "$AI_MODEL"] --include-directories <projects dir> --output-format text --prompt "<prompt>" (puntual) / -i "<prompt>" (interactivo).
  • Aider: aider --no-check-update --no-pretty --no-auto-commits --subtree-only [--no-git] [--model "$AI_MODEL"] [--api-key <provider>="$AI_API_KEY"] [--openai-api-base "$AI_API_BASE"] --message "<prompt>" (puntual). El --message de Aider termina después de responder, así que las ejecuciones interactivas inician la sesión con --load y luego te la devuelven. Se añade --no-git cuando el directorio todavía no es un repositorio git.
  • OpenCode: opencode run [-m "$AI_MODEL"] "<prompt>" (puntual) / opencode [-m ...] --prompt "<prompt>" (interactivo). La clave va a la variable que lee el proveedor del modelo; un endpoint se convierte en un proveedor compatible con OpenAI llamado zeltro en OPENCODE_CONFIG_CONTENT, con el modelo como zeltro/<model>. La actualización automática se desactiva durante la ejecución.
  • Hermes: hermes chat [--provider <p>] [-m <model>] --oneshot -Q -q "<prompt>" (puntual) / hermes chat [...] -q "<prompt>" (interactivo). Un prefijo de modelo (openai/, openrouter/, anthropic/, gemini/) se convierte en --provider; un endpoint usa --provider openai con OPENAI_BASE_URL y OPENAI_API_KEY.
• Pasa opciones para saltarse la aprobación solo cuando se le indica. De forma predeterminada, si un agente trabaja sin preguntar queda registrado en la configuración propia del agente (~/.claude/settings.json, ~/.codex/config.toml, ~/.gemini/antigravity-cli/settings.json, ~/.gemini/settings.json, ~/.qwen/settings.json, ~/.aider.conf.yml, ~/.config/opencode/opencode.json, ~/.hermes/config.yaml), y se define con zeltro ai-set --allow-unattended o zeltro ai-unattended. Para una sola ejecución, ZELTRO_AI_UNATTENDED=1 añade las opciones (la app de escritorio lo usa para su interruptor por proyecto; ZELTRO_AI_AUTO_APPROVE=1 sigue funcionando) y ZELTRO_AI_UNATTENDED=0 activa en cambio las aprobaciones. Con 1 pasa (--dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox, --yolo, --dangerously-skip-permissions para agy, --yolo --skip-trust para Gemini, --yes-always para Aider, --auto para OpenCode, --yolo para Hermes).

🎯 Opciones de los comandos#

Opciones globales#

Opciones de un proyecto nuevo#

zeltro new <framework> <name>: el framework y el nombre son argumentos posicionales obligatorios. El framework es uno de estos: laravel, kavera, octobercms, drupal, wordpress, php, fastapi, flask, django, python, express, nestjs, fastify, node, nextjs, nuxt, sveltekit, astro, hono, react, vue.

Opciones para clonar un proyecto#

zeltro clone <mode> <repo> [name]: el modo es un primer argumento obligatorio: work-directly (clona y mantiene el original como upstream), fork (hace un fork en tu cuenta de GitHub) o new-repo (crea un repositorio nuevo de GitHub para él).

Proyectos complejos: al clonar un proyecto que trae su propio docker-compose con varios servicios (base de datos, caché y workers incluidos), Zeltro lo adapta automáticamente: elimina los servicios de base de datos y caché incluidos y redirige sus variables de entorno a los contenedores compartidos de Zeltro (zeltro-postgres, zeltro-mariadb, zeltro-redis, zeltro-mongo). El servicio web recibe una IP fija en la VPC. El tipo de imagen solo afecta a esta adaptación del compose: los pasos del framework (composer install, la configuración del .env, las migraciones) dependen de la detección del framework y también se ejecutan en los proyectos adaptados. Pasa --no-startup para revisar el compose adaptado antes de que arranque, --overwrite-env para apuntar los ajustes de conexión del .env de una app existente a los servicios compartidos (conservando APP_KEY) y --no-migration para omitir las migraciones.

Opciones de configuración de un proyecto#

zeltro setup <project> [database]: el segundo argumento, opcional, es el motor de base de datos (mysql, postgres, mongo, sqlite; predeterminado mysql).

Opciones de status#

Un proyecto indicado por nombre (zeltro status my-project) se muestra aunque esté detenido.

Opciones para eliminar un proyecto#

Por defecto, los archivos del proyecto se mueven a la papelera, y la base de datos y los volúmenes de Docker del proyecto se conservan.

Opciones para cambiar el nombre de un proyecto#

zeltro rename <project> <new-name> se niega mientras haya algo en ejecución dentro de la carpeta del proyecto (una sesión de IA, una terminal), así que ciérralo primero. En una carpeta añadida con zeltro add, solo cambia el nombre del proyecto; la carpeta se queda donde está.

Opciones de desinstalación#

Opciones de configure#

Volver a ejecutar zeltro configure es seguro: los valores de /etc/zeltro-cli/.env se conservan como predeterminados y las preguntas te permiten cambiarlos. Zeltro no escribe en /etc/hosts.

💡 Ejemplos de uso#

Clonar y configurar proyectos#

# Clone a Git repository and set it up automatically
zeltro clone work-directly https://github.com/user/my-laravel-app

# Clone with a custom local name
zeltro clone work-directly https://github.com/user/company-project my-local-name

# Manual Git clone into the projects directory, then setup
cd "$(zeltro projects-dir)"
git clone https://github.com/user/company-project
zeltro setup company-project
zeltro up company-project

# Downloaded ZIP file - extract to ~/zeltro-projects/company-project/
zeltro setup company-project
zeltro up company-project

# Copied project folder
cp -r existing-project ~/zeltro-projects/new-project
zeltro setup new-project --overwrite-docker-compose

Desarrollo con WordPress#

# Create a WordPress project (MySQL is auto-selected)
zeltro new wordpress wp-site --version latest

# Install and activate plugins
cd ~/zeltro-projects/wp-site
zeltro wp plugin install woocommerce --activate
zeltro wp plugin list --status=active

Salida JSON para automatización#

# Get project status as JSON for scripts/GUI
zeltro status --json-output

# Create project with JSON response
zeltro new fastapi my-api --database postgres --json-output

# Check if a shared service is running (keys are container names; status is lowercase)
if [ "$(zeltro status --json-output | jq -r '.shared_services["zeltro-mariadb"].status')" = "running" ]; then
    echo "Database is ready"
fi

# Batch project operations (--all so stopped projects are included)
for project in $(zeltro status --all --json-output | jq -r '.projects[].name'); do
    zeltro up $project --json-output
done

Cómo leer los campos de dirección

Cada proyecto en zeltro status --json-output incluye varios campos de dirección. Significan cosas distintas, y uno de ellos es fácil de usar mal:

Gestión de servicios#

# Check Redis status and flush cache
zeltro redis ping
zeltro redis-flush

# Monitor supervised processes (from the project directory)
zeltro supervisor-status
zeltro supervisor restart all

Uso avanzado#

Comandos de desarrollo en el contenedor

Proyectos PHP: zeltro composer, zeltro art, zeltro php, zeltro wp y zeltro drush se ejecutan dentro del contenedor de tu proyecto con el entorno PHP correcto:

cd ~/zeltro-projects/my-laravel-app
zeltro composer install        # Uses container's PHP 8.3
zeltro art migrate             # Runs with container's Laravel setup
zeltro php script.php          # Executes with project's PHP configuration

Proyectos Node.js: zeltro npm, zeltro npx y zeltro node se ejecutan dentro del contenedor de tu proyecto con Node 22:

cd ~/zeltro-projects/my-express-app
zeltro npm install             # Installs packages inside container
zeltro npx tsc --init         # Run any npx command inside container
zeltro node script.js         # Execute a script with project's Node environment

Proyectos Python (FastAPI, Django, Python a secas): zeltro python y zeltro pip se ejecutan dentro del contenedor de tu proyecto:

cd ~/zeltro-projects/my-fastapi-app
zeltro python -c "import sys; print(sys.version)"
zeltro pip install httpx              # Install a package inside the container
zeltro pip list                       # Show installed packages

Proyectos Django: usa los envoltorios zeltro django para las operaciones de manage.py:

cd ~/zeltro-projects/my-django-app
zeltro django manage migrate          # Run migrations
zeltro django manage createsuperuser  # Create admin user
zeltro django manage collectstatic    # Collect static files
zeltro django manage makemigrations myapp

Shells interactivas y REPL

zeltro shell abre automáticamente el entorno interactivo adecuado para el proyecto actual:

# Laravel — opens php artisan tinker
cd ~/zeltro-projects/my-laravel-app && zeltro shell

# Django — opens python manage.py shell (Django ORM and apps loaded)
cd ~/zeltro-projects/my-django-app && zeltro shell

# FastAPI / plain Python / Python script — opens python3 REPL
cd ~/zeltro-projects/my-fastapi-app && zeltro shell

# Express / Fastify / plain Node.js — opens node REPL
cd ~/zeltro-projects/my-express-app && zeltro shell

# NestJS — opens node REPL; or the NestJS REPL if src/repl.ts exists
cd ~/zeltro-projects/my-nest-app && zeltro shell

Todo lo que no puede detectar recibe una shell bash. zeltro tinker sigue disponible como alias explícito, solo para Laravel.

El REPL de NestJS (src/repl.ts) no se crea por defecto. Créalo según la documentación del REPL de NestJS y zeltro shell lo usará automáticamente.

🔌 Integración mediante la API JSON#

Zeltro ofrece una salida JSON limpia para la integración programática, ideal para aplicaciones con interfaz gráfica y scripts de automatización:

// Example: Create project via JSON API
const result = await exec('zeltro new laravel myapp --version 12.9.1 --json-output');
const data = JSON.parse(result.stdout);

// Result:
{
  "action": "new_project",
  "project_name": "myapp",
  "framework": "laravel",
  "database": "mysql",
  "setup_result": { ... },
  "status": "success"
}

Comandos con salida JSON#

✅ Admiten JSON:

• zeltro status --json-output - Estado de los proyectos y servicios
• zeltro new --json-output - Confirmación de la creación del proyecto
• zeltro clone --json-output - Confirmación de la clonación del proyecto
• zeltro setup --json-output - Confirmación de la configuración del proyecto
• zeltro remove --json-output - Confirmación de la eliminación del proyecto
• zeltro up --json-output - Confirmación del inicio del proyecto
• zeltro down --json-output - Confirmación de la detención del proyecto
• zeltro start-services --json-output - Confirmación del inicio de los servicios
• zeltro stop-services --json-output - Confirmación de la detención de los servicios
• zeltro enable-service / disable-service --json-output - Resultado de activar o desactivar el servicio (sin nombre: lista los servicios opcionales)
• zeltro configure --json-output - Confirmación de la configuración
• zeltro uninstall --json-output - Confirmación de la desinstalación
• zeltro ai-set --json-output - Ajustes de IA actuales (de solo lectura cuando se usa sola)
• zeltro create --classify-only --json-output - Clasificación del stack
• zeltro peers --json-output / zeltro send --json-output - Sesiones de agentes / resultado del envío
• zeltro get-metadata --json-output - Todas las claves de x-metadata, incluida la idea completa (status solo informa de has_idea)
• zeltro set-metadata, zeltro disable, zeltro enable --json-output - Resultado
• zeltro projects-dir --json-output, zeltro version --json-output

❌ No admiten JSON (comandos del contenedor):

• zeltro composer - Se ejecuta dentro del contenedor
• zeltro art - Se ejecuta dentro del contenedor
• zeltro wp - Se ejecuta dentro del contenedor
• zeltro drush - Se ejecuta dentro del contenedor
• zeltro php - Se ejecuta dentro del contenedor
• zeltro npm - Se ejecuta dentro del contenedor
• zeltro npx - Se ejecuta dentro del contenedor
• zeltro node - Se ejecuta dentro del contenedor
• zeltro python - Se ejecuta dentro del contenedor
• zeltro pip - Se ejecuta dentro del contenedor
• zeltro shell - Se ejecuta dentro del contenedor
• zeltro django - Se ejecuta dentro del contenedor
• zeltro exec - Se ejecuta dentro del contenedor
• zeltro exec-root - Se ejecuta dentro del contenedor
• zeltro supervisor - Se ejecuta dentro del contenedor
• zeltro redis - Conexión directa al servicio
• zeltro memcache - Conexión directa al servicio

🏗️ Arquitectura#

Servicios incluidos#

Siempre en ejecución:

• Redis (zeltro-redis) - Caché y almacenamiento de sesiones
• Memcached (zeltro-memcached) - Capa de caché adicional
• MailHog (zeltro-mailhog) - Pruebas y depuración de correo (captura los correos salientes)

Opcionales: se activan automáticamente cuando un proyecto necesita uno, o con zeltro enable-service:

• MariaDB (zeltro-mariadb), PostgreSQL (zeltro-postgres), MongoDB (zeltro-mongo)
• phpMyAdmin, Adminer, mongo-express, RedisInsight - Interfaces de administración de bases de datos
• MinIO (almacenamiento compatible con S3, servido por Silo, el fork mantenido de MinIO), Meilisearch (búsqueda de texto completo)

Estructura de un proyecto#

~/zeltro-projects/
├── project1/
│   ├── docker-compose.yaml
│   ├── .env
│   └── [project files]
├── project2/
└── ...

Configuración de red#

Cada proyecto recibe:

• Una dirección IP de Docker única (10.x.x.x) en la red zeltro-cli_vpc
• Un nombre que se resuelve en la red compartida, desde dentro de cualquier contenedor
• Un puerto externo asignado para acceder desde la LAN
• URL local: la IP del contenedor, por ejemplo http://10.247.177.219
• URL LAN: http://your-ip:port

Desinstalación#

Desinstalación según la plataforma#

🐧 Linux y 🍎 macOS

# 1. Remove Zeltro's containers, volumes and networks, and the CLI itself
#    (/usr/local/bin/zeltro and /usr/local/share/zeltro-cli)
zeltro uninstall

# 2. Remove configuration directory (optional)
sudo rm -rf /etc/zeltro-cli

Si instalaste el paquete .deb, ejecuta zeltro uninstall y luego sudo apt remove zeltro-cli.

Qué se elimina#

zeltro uninstall elimina:

• ✅ Todos los contenedores de servicios de Zeltro (mariadb, redis, postgres, etc.)
• ✅ Todos los contenedores de cada proyecto
• ✅ Las imágenes de Docker (opcional, con --delete-images)
• ✅ Los volúmenes y redes de Docker con el prefijo zeltro-cli_, incluidos los datos de las bases de datos compartidas
• ✅ El binario y los archivos fuente de la CLI de Zeltro
• ✅ Guarda una copia de los docker-compose.yaml de los proyectos como docker-compose.yaml.backup

Qué se conserva:

• ✅ El código fuente y los archivos de tus proyectos
• ✅ La configuración de /etc/zeltro-cli (una reinstalación la recupera)
• ✅ Los demás contenedores e imágenes de Docker que no son de Zeltro
• ✅ Docker Desktop/Engine en sí

Consulta las Opciones de desinstalación para ver las opciones.

🔧 Configuración#

Configuración inicial#

# Run the configuration wizard
zeltro configure

zeltro configure también instala el autocompletado con tabulador para bash (en /usr/share/bash-completion/completions/zeltro y /etc/bash_completion.d/zeltro, los que existan). Abre una shell nueva y usa el tabulador con los comandos, los nombres de proyecto y los nombres de instalador:

zeltro ins<TAB>            → install
zeltro install gr<TAB>     → grafana  gramps-web  graylog  grist  grocy
zeltro up <TAB>            → (your project names)
zeltro new <TAB>           → laravel  wordpress  fastapi  django  ...
zeltro clone <TAB>         → work-directly  fork  new-repo

Variables de entorno#

• JSON_OUTPUT=1 - Igual que --json-output
• NO_COLOR - Cualquier valor: igual que --no-colors
• FORCE_COLOR=1 - Mantiene el color cuando la salida se canaliza o se redirige (ahí está desactivado de forma predeterminada), por ejemplo zeltro status | less -R
• DEBUG_LOG_PATH - Dónde escribe --debug (predeterminado /tmp/zeltro-cli-debug.log)
• ZELTRO_AI_AGENT, ZELTRO_AI_MODEL, ZELTRO_AI_API_BASE, ZELTRO_AI_API_KEY, ZELTRO_AI_API_KEY_FILE, ZELTRO_AI_LANGUAGE - ajustes de IA por sesión (consulta "Ajustes de IA por sesión" en Gestión del sistema)
• ZELTRO_AI_UNATTENDED=1 / 0 - Solo para esta ejecución: 1 ejecuta el agente sin pedir aprobación, 0 las activa aunque su configuración diga lo contrario (sin definir: decide su configuración). ZELTRO_AI_AUTO_APPROVE=1 es la forma antigua de escribir 1
• ZELTRO_BUS_DIR - Cola de mensajes de los agentes (predeterminado ~/.zeltro/bus)

El directorio de proyectos no es una variable de entorno: es PROJECTS_DIR en /etc/zeltro-cli/.env, y se define con zeltro configure --projects-dir.

📝 Notas importantes#

• Directorio requerido: las herramientas del proyecto (composer, art, wp, drush, php, npm, npx, node, python, pip, shell, django, exec, db-refresh, cache-refresh, supervisor) y ai / send deben ejecutarse desde dentro de un directorio de proyecto
• Salida JSON: usa --json-output para la integración programática (interfaz gráfica, scripts, automatización)
• Modo no interactivo: los comandos reciben argumentos explícitos y nunca muestran selectores. configure y create solo preguntan en una terminal; en scripts usa configure --non-interactive o create --one-off
• Creación de bases de datos: las bases de datos se crean y configuran automáticamente para cada proyecto, y el servicio compartido del motor se activa si todavía no lo está
• Direcciones: a cada proyecto se le asigna una IP de contenedor y un puerto publicado; no se escribe nada en /etc/hosts

🚦 Obtener ayuda#

# Show comprehensive help
zeltro help

# Show command-specific help
zeltro new --help
zeltro remove --help

🔍 Solución de problemas#

Problemas frecuentes#

1. Los servicios no arrancan: comprueba que Docker esté en ejecución y que los puertos estén libres
2. Errores de permisos: asegúrate de que el usuario esté en el grupo docker
3. Conexión a la base de datos: comprueba que el servicio de base de datos esté en ejecución con zeltro status, y actívalo con zeltro enable-service <mysql|postgres|mongo> si no lo está
4. Conflictos de puertos: cada proyecto recibe automáticamente un puerto único

Comandos de depuración#

# Check service status
zeltro status

# View container logs
docker logs [container-name]

# Check that a shared service resolves from inside the project container
zeltro exec "getent hosts zeltro-redis"

# Enable debug logging
zeltro new laravel my-project --debug
zeltro setup my-project --debug
zeltro configure --debug

# View debug log
cat /tmp/zeltro-cli-debug.log

Modo de depuración#

Los principales comandos de proyectos y servicios aceptan una opción --debug (consulta las Opciones globales) que escribe registros detallados para ayudar a resolver problemas:

• Ubicación del registro: /tmp/zeltro-cli-debug.log
• Seguimiento por sesión: cada comando nuevo crea una sesión de depuración nueva
• Salida detallada: muestra el flujo de los scripts, las llamadas a funciones y los códigos de salida
• Seguimiento entre scripts: la opción de depuración se pasa automáticamente entre scripts

Ejemplo:

# Debug a project creation issue
zeltro new laravel test-project --debug

# Check what happened
tail -f /tmp/zeltro-cli-debug.log

Consulta Automatización y JSON para ver qué comandos admiten JSON y cómo escribir scripts con ellos.

¿Encontraste un error en esta traducción? Avísanos en GitHub.