Referência de comandos

Rode zeltro --help para ver a mesma lista no terminal, ou zeltro <command> --help para um comando específico.

Os comandos marcados com (diretório do projeto) precisam ser executados de dentro de um diretório de projeto.

🛠️ Ferramentas de desenvolvimento#

Rode a partir do diretório do projeto

✅ Análise estática e linting#

Rode a partir do diretório do projeto; os caminhos são relativos à raiz do projeto (por exemplo app/Console/Commands/Foo.php)

📦 Execução no contêiner#

Rode a partir do diretório do projeto

⚡ Comandos extras para Laravel#

Rode a partir do diretório do projeto

🐍 Comandos extras para Django#

Rode a partir do diretório do projeto

🔧 Gerenciamento de serviços#

Rode de qualquer lugar

🎛️ Gerenciamento de processos#

Rode a partir do diretório do projeto

📁 Gerenciamento de projetos#

O zeltro status imprime endereços que você pode abrir a partir do host: http://<container-ip> localmente (ou http://localhost:<port> no macOS) e http://<host-lan-ip>:<port> a partir da LAN. http://<project>/ não funciona a partir do host — os nomes dos projetos só são resolvidos dentro dos contêineres. Não existe zeltro ps.

⚙️ Gerenciamento do sistema#

Serviços compartilhados opcionais

Só o Redis, o Memcached e o MailHog rodam sempre. Todo o resto fica desligado até ser ativado, e a lista de ativados fica guardada em OPTIONAL_SERVICES em /etc/zeltro-cli/.env. zeltro new, zeltro setup e zeltro install ativam automaticamente o banco de dados de que um projeto precisa.

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

Um serviço só é registrado como ativado se iniciar e continuar rodando. Em uma máquina instalada antes da mudança de nome para Zeltro, rode zeltro migrate-names para passar os contêineres para os nomes zeltro-*.

Mensagens entre sessões de agentes

Quando o app Zeltro hospeda sessões de agentes em vários projetos (em um host ou em vários), elas podem trocar mensagens. O app faz o roteamento por uma fila por usuário em ~/.zeltro/bus/: ele publica o peers.json, e o send deixa um arquivo JSON por mensagem em 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

• Rode o send de dentro do diretório do seu projeto; é assim que você é identificado.
• Um project sozinho funciona quando só uma sessão ativa tem esse nome; caso contrário, use project@host.
• Todos os destinos precisam ser sessões ativas, senão nada é enviado. As mensagens têm limite de 16 KB.
• Com um único destino, o -- é opcional: zeltro send blog "message".
• Saída 0 significa que a mensagem entrou na fila. Ela chega ao terminal do destino como [Zeltro message from <you>@<host> to <targets>] ....

Pedindo coisas ao app Zeltro

Um agente em uma sessão iniciada pelo app Zeltro pode usar a janela do app para falar com o usuário:

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 saída: 0 ok, 1 erro, 2 uso incorreto, 3 o app não está disponível (pergunte no chat), 4 tempo esgotado, 5 o usuário recusou, 6 o app recusou. O secret só escreve em arquivos dentro do projeto.

zeltro ai e zeltro resume também avisam o app quando cada turno termina, usando o zeltro gui event como hook para o Claude Code, o Codex e o aider. As flags de hook valem só para aquela execução e não alteram os seus arquivos de configuração, e o do Codex é pulado se você tiver definido o seu próprio notify.

Opções do zeltro ai-set

O zeltro ai-set gerencia o CLI de agente de IA global, o modelo e a chave de API usados pelo 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

Flags suportadas:

• --agent <name> – Define o CLI do agente de IA (codex, claude, agy, qwen, aider, opencode ou hermes). gemini ainda funciona, mas está obsoleto: o Google deixou de oferecer o Gemini CLI para contas pessoais em 2026-06-18, então use agy, o Antigravity CLI que o substitui.
• --model <name> – Define o nome do modelo (opcional para Codex, Claude, agy, Gemini, OpenCode e Hermes; obrigatório para Qwen e Aider, e para OpenCode e Hermes com --api-base). OpenCode e Hermes recebem provider/model, por exemplo openai/gpt-5.4-mini.
• --api-key <key> – Define a chave de API da IA (opcional para Codex, Claude, agy, OpenCode e Hermes; para agy e Gemini, uma chave de API do Gemini, passada como GEMINI_API_KEY; obrigatória para Aider). --api-key "" apaga uma chave guardada.
• --api-base <url> – Define um endpoint de API personalizado: compatível com OpenAI para Codex, Qwen, Aider, OpenCode e Hermes; um proxy compatível com Anthropic para Claude. --api-base none o apaga.
• --allow-unattended / --no-allow-unattended – Deixa o agente rodar sem pedir aprovação, ou desliga isso. Gravado na configuração do próprio agente; omita as duas para não mudar nada. É o que as execuções no terminal seguem; no app desktop, o botão "Trabalha sem perguntar" de cada projeto (ligado por padrão) passa por cima disso a cada sessão, via ZELTRO_AI_UNATTENDED.
• --install-only – Com --agent: instala o CLI desse agente se estiver faltando, sem torná-lo o padrão. Não escreve nada na configuração do Zeltro.
• --json-output – Devolve o resultado como JSON (não interativo). Sozinho, zeltro ai-set --json-output é uma consulta somente leitura: não instala nem escreve nada, e informa as configurações atuais mais "session_overrides": true, "ai_language": true e "installed_agents": [...].

Trocar o --agent sem --model ou --api-base apaga o modelo e o endpoint anteriores.

Exemplos:

• Ver as configurações de IA atuais:
  • zeltro ai-set --json-output
• Configurar o Codex com um modelo:
  • zeltro ai-set --agent codex --model gpt-6-sol
• Configurar o Claude com um modelo:
  • zeltro ai-set --agent claude --model opus
• Configurar o Aider com a Anthropic:
  • zeltro ai-set --agent aider --model anthropic/claude-sonnet-5 --api-key sk-ant-...
• Configurar o Aider com um servidor Ollama local:
  • zeltro ai-set --agent aider --model openai/llama3.1 --api-key ollama --api-base http://localhost:11434/v1

Substituições de IA por sessão

zeltro ai, resume, create (inclusive --classify-only), clone, create-installer e update-installer usam o agente definido pelo zeltro ai-set. Para usar outro em uma única execução, defina estas variáveis de ambiente. Elas nunca são escritas em /etc/zeltro-cli/.env.

Não definida significa "usar o valor do ai-set"; definida mas vazia significa "apagar o valor nesta execução". Um agente desconhecido, um arquivo de chave ilegível ou um agente de substituição que não está instalado é um erro antes de qualquer coisa rodar, e nada é instalado — use zeltro ai-set --install-only --agent <name> antes.

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

O Aider é o único agente suportado sem login próprio — ele sempre fala diretamente com a API de um provedor, então precisa de um modelo e de uma chave.

• O nome do modelo escolhe o provedor: openai/gpt-6-sol, anthropic/claude-sonnet-5, gemini/gemini-2.5-pro, deepseek/deepseek-chat. Veja a lista de modelos do aider.
• O Aider marca as chaves por provedor (--api-key openai=sk-...). O Zeltro guarda a chave pura e a marca a partir do prefixo do modelo, então --api-key sk-... é tudo de que você precisa. Uma chave que já contém = é repassada como está.
• O --api-base só é necessário para um servidor compatível com OpenAI — Ollama, LM Studio, OpenRouter, vLLM. Ponha o prefixo openai/ no modelo quando usar um deles. Deixe-o em branco para a API hospedada do próprio provedor.
• O Zeltro roda o Aider com --no-auto-commits, então as edições dele caem na sua árvore de trabalho como as de qualquer outro agente, em vez de serem commitadas automaticamente.

🤖 Criação de projetos com IA#

O zeltro create recebe a sua ideia de projeto, acrescenta instruções específicas do Zeltro e entrega o prompt combinado ao CLI de IA que você configurou. O Zeltro prepara o ambiente. A IA constrói o 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"

Passe --one-off para parar depois da criação e pular a entrega para a IA.

O que o agente de IA faz:

1. Se o framework ou a stack não estiver claro, pergunta qual usar antes de continuar.
2. Roda zeltro new para criar o projeto e iniciar os contêineres dele.
3. Lê o arquivo .env gerado para entender a configuração de banco de dados, cache e e-mail.
4. Constrói o app seguindo as convenções nativas do framework: migrations, models, seeders, rotas, controllers, templates.
5. Atualiza o README do projeto com a URL local, comandos úteis e as credenciais padrão, se houver.

Se a sua ideia corresponder a um app conhecido que tem um instalador do Zeltro (Grafana, Gitea, n8n, Portainer etc.), o agente roda zeltro install <name> primeiro — deixando-o no ar em segundos — e depois aplica as personalizações adicionais do seu prompt. Você nunca precisa escrever um arquivo docker-compose nem saber em que porta o app escuta.

O CLI de IA pode ser na nuvem ou local, conforme a sua configuração. Use zeltro ai-set para escolher qual agente é usado.

Só classificar (para interfaces gráficas e outros front ends)

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

Roda só a fase de classificação: descobre a stack, imprime o resultado, sai com 0 e não cria nada. Nunca faz perguntas, então é seguro chamá-lo a partir de uma interface gráfica, de um script ou de um agente.

Isso existe porque o caminho não interativo normal (--one-off, --json-output) aceita em silêncio a primeira recomendação — ótimo para automação, mas descarta a escolha que uma pessoa teria feito no menu. Um front end que queira apresentar essas opções de forma nativa deve classificar primeiro, mostrar os candidatos e depois chamar zeltro install <app> ou zeltro new <framework> <name> com o que o usuário escolheu.

O JSON traz project_name (null quando a ideia não sugere um assunto concreto, então pergunte em vez de preencher), recommended, customization_requested, um database sugerido com o motivo, e candidates — apps primeiro, framework por último, no máximo 5. Apps trazem um único database fixo, definido pelo instalador; frameworks trazem um array databases com os motores que aceitam. Nunca ofereça escolha de banco de dados para um app. Em caso de falha, ele emite {"action": "classify", "status": "error", "message": "..."} e sai com código diferente de zero.

🤖 Sessões de agentes de IA#

Depois de definir o seu agente de IA global com zeltro ai-set, você pode enviar um prompt de qualquer diretório de projeto do Zeltro:

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

Por padrão, o zeltro ai envia um prompt de execução única — o agente o recebe, faz o trabalho e sai. O contexto duradouro do projeto fica no AGENTS.md do projeto (o Zeltro o escreve na criação), então cada prompt pode ser independente. Acrescente --interactive (-i) se preferir uma sessão persistente. --one-off ainda é aceito por compatibilidade.

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

O zeltro ai:

• Lê AI_AGENT, AI_MODEL, AI_API_KEY e AI_API_BASE de /etc/zeltro-cli/.env, a menos que haja uma substituição ZELTRO_AI_* definida.
• Roda o agente com o prompt (as partes [...] só entram quando definidas):
  • Codex: codex exec [--model "$AI_MODEL"] "<prompt>" (execução única) / codex [--model ...] "<prompt>" (interativo). Chave via OPENAI_API_KEY; o endpoint é passado como -c openai_base_url="…", porque o Codex atual ignora OPENAI_BASE_URL.
  • Claude: claude -p [--model "$AI_MODEL"] "<prompt>" (-p só na execução única). Chave via ANTHROPIC_API_KEY, endpoint via ANTHROPIC_BASE_URL.
  • O Codex e o Claude removeram as flags --api-key; a chave passa pelo ambiente. O Zeltro confere se a chave parece ser daquele provedor (sk- para Codex, sk-ant- para Claude) e, se não for, a ignora com um aviso e deixa o CLI usar o próprio login — uma chave do provedor errado substituiria uma autenticação que funciona por outra que não tem como funcionar.
  • Qwen: qwen --auth-type openai [--model "$AI_MODEL"] --prompt "<prompt>" (execução única) / -i "<prompt>" (interativo). Chave e endpoint via OPENAI_API_KEY / OPENAI_BASE_URL.
  • agy (Antigravity CLI): agy [--model "$AI_MODEL"] --add-dir <projects dir> -p "<prompt>" (execução única) / -i "<prompt>" (interativo). Chave via GEMINI_API_KEY, com "modelProvider": "gemini" definido em ~/.gemini/antigravity-cli/settings.json enquanto houver uma chave guardada; sem endpoint personalizado.
  • Gemini (obsoleto): gemini [--model "$AI_MODEL"] --include-directories <projects dir> --output-format text --prompt "<prompt>" (execução única) / -i "<prompt>" (interativo).
  • 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>" (execução única). O --message do Aider sai depois da resposta, então as execuções interativas iniciam a sessão com --load e a devolvem para você. --no-git é acrescentado quando o diretório ainda não é um repositório git.
  • OpenCode: opencode run [-m "$AI_MODEL"] "<prompt>" (execução única) / opencode [-m ...] --prompt "<prompt>" (interativo). A chave vai para a variável que o provedor do modelo lê; um endpoint vira um provedor compatível com OpenAI chamado zeltro em OPENCODE_CONFIG_CONTENT, com o modelo como zeltro/<model>. A atualização automática fica desligada durante a execução.
  • Hermes: hermes chat [--provider <p>] [-m <model>] --oneshot -Q -q "<prompt>" (execução única) / hermes chat [...] -q "<prompt>" (interativo). Um prefixo de modelo (openai/, openrouter/, anthropic/, gemini/) vira --provider; um endpoint usa --provider openai com OPENAI_BASE_URL e OPENAI_API_KEY.
• Só passa flags que dispensam aprovação quando mandado. Por padrão, se um agente roda sem perguntar fica registrado na configuração do próprio 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), definido com zeltro ai-set --allow-unattended ou zeltro ai-unattended. Para uma execução, ZELTRO_AI_UNATTENDED=1 acrescenta as flags (o app desktop usa isso no botão de cada projeto; ZELTRO_AI_AUTO_APPROVE=1 continua funcionando) e ZELTRO_AI_UNATTENDED=0 liga os pedidos de aprovação. Com 1, ele passa (--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).

🎯 Opções dos comandos#

Opções globais#

Opções de projeto novo#

zeltro new <framework> <name> — framework e nome são argumentos posicionais obrigatórios. O framework é um destes: laravel, kavera, octobercms, drupal, wordpress, php, fastapi, flask, django, python, express, nestjs, fastify, node, nextjs, nuxt, sveltekit, astro, hono, react, vue.

Opções de clonagem#

zeltro clone <mode> <repo> [name] — o modo é o primeiro argumento, obrigatório: work-directly (clona e mantém o original como upstream), fork (faz um fork na sua conta do GitHub) ou new-repo (cria um repositório novo no GitHub para ele).

Projetos complexos: ao clonar um projeto que traz o próprio docker-compose com vários serviços (banco de dados, cache e workers embutidos), o Zeltro o adapta automaticamente: os serviços de banco de dados e cache embutidos são removidos e as variáveis de ambiente deles passam a apontar para os contêineres compartilhados do Zeltro (zeltro-postgres, zeltro-mariadb, zeltro-redis, zeltro-mongo). O serviço exposto à web recebe um IP estático na VPC. O tipo de imagem só afeta essa adaptação do compose — as etapas do framework (composer install, configuração do .env, migrations) dependem da detecção do framework e também rodam em projetos adaptados. Passe --no-startup para revisar o compose adaptado antes de ele subir, --overwrite-env para apontar as configurações de conexão do .env de um app existente para os serviços compartilhados (preservando o APP_KEY) e --no-migration para pular as migrations.

Opções de setup#

zeltro setup <project> [database] — o segundo argumento, opcional, é o motor de banco de dados (mysql, postgres, mongo, sqlite; padrão mysql).

Opções do status#

Um projeto nomeado (zeltro status my-project) aparece mesmo parado.

Opções de remoção#

Por padrão, os arquivos do projeto vão para a lixeira, e o banco de dados e os volumes Docker do projeto são mantidos.

Opções de renomeação#

O zeltro rename <project> <new-name> se recusa a rodar enquanto houver algo em execução dentro da pasta do projeto (uma sessão de IA, um terminal), então feche essas coisas antes. Para uma pasta adicionada com zeltro add, só o nome do projeto muda; a pasta fica onde está.

Opções de desinstalação#

Opções do configure#

Rodar o zeltro configure de novo é seguro — os valores de /etc/zeltro-cli/.env são mantidos como padrão, e as perguntas deixam você alterá-los. O Zeltro não escreve no /etc/hosts.

💡 Exemplos de uso#

Clonando e configurando projetos#

# 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

Desenvolvimento com 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

Saída JSON para automação#

# 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

Lendo os campos de endereço

Cada projeto em zeltro status --json-output traz vários campos de endereço. Eles significam coisas diferentes, e um deles é fácil de usar errado:

Gerenciamento de serviços#

# 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 avançado#

Comandos de desenvolvimento no contêiner

Projetos PHP — zeltro composer, zeltro art, zeltro php, zeltro wp e zeltro drush rodam dentro do contêiner do seu projeto, com o ambiente PHP correto:

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

Projetos Node.js — zeltro npm, zeltro npx e zeltro node rodam dentro do contêiner do seu projeto, com o 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

Projetos Python (FastAPI, Django, Python puro) — zeltro python e zeltro pip rodam dentro do contêiner do seu projeto:

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

Projetos Django — use os wrappers zeltro django para as operações do 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 interativos e REPLs

O zeltro shell abre automaticamente o ambiente interativo certo para o projeto atual:

# 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

O que ele não conseguir detectar recebe um shell bash. O zeltro tinker continua disponível como alias explícito, só para Laravel.

O REPL do NestJS (src/repl.ts) não é criado por padrão. Crie-o seguindo a documentação do REPL do NestJS, e o zeltro shell passa a usá-lo automaticamente.

🔌 Integração via API JSON#

O Zeltro oferece saída JSON limpa para integração programática, ideal para aplicativos com interface gráfica e scripts de automação:

// 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 com JSON disponível#

✅ Com suporte a JSON:

• zeltro status --json-output - Status dos projetos e serviços
• zeltro new --json-output - Confirmação da criação do projeto
• zeltro clone --json-output - Confirmação da clonagem do projeto
• zeltro setup --json-output - Confirmação do setup do projeto
• zeltro remove --json-output - Confirmação da remoção do projeto
• zeltro up --json-output - Confirmação da inicialização do projeto
• zeltro down --json-output - Confirmação do desligamento do projeto
• zeltro start-services --json-output - Confirmação do início dos serviços
• zeltro stop-services --json-output - Confirmação da parada dos serviços
• zeltro enable-service / disable-service --json-output - Resultado da ativação/desativação do serviço (sem nome: lista os serviços opcionais)
• zeltro configure --json-output - Confirmação da configuração
• zeltro uninstall --json-output - Confirmação da desinstalação
• zeltro ai-set --json-output - Configurações de IA atuais (somente leitura quando usado sozinho)
• zeltro create --classify-only --json-output - Classificação da stack
• zeltro peers --json-output / zeltro send --json-output - Sessões de agentes / resultado do envio
• zeltro get-metadata --json-output - Todas as chaves de x-metadata, inclusive a idea completa (o status só informa has_idea)
• zeltro set-metadata, zeltro disable, zeltro enable --json-output - Resultado
• zeltro projects-dir --json-output, zeltro version --json-output

❌ Sem suporte a JSON (comandos no contêiner):

• zeltro composer - Roda dentro do contêiner
• zeltro art - Roda dentro do contêiner
• zeltro wp - Roda dentro do contêiner
• zeltro drush - Roda dentro do contêiner
• zeltro php - Roda dentro do contêiner
• zeltro npm - Roda dentro do contêiner
• zeltro npx - Roda dentro do contêiner
• zeltro node - Roda dentro do contêiner
• zeltro python - Roda dentro do contêiner
• zeltro pip - Roda dentro do contêiner
• zeltro shell - Roda dentro do contêiner
• zeltro django - Roda dentro do contêiner
• zeltro exec - Roda dentro do contêiner
• zeltro exec-root - Roda dentro do contêiner
• zeltro supervisor - Roda dentro do contêiner
• zeltro redis - Conexão direta com o serviço
• zeltro memcache - Conexão direta com o serviço

🏗️ Arquitetura#

Serviços incluídos#

Sempre rodando:

• Redis (zeltro-redis) - Cache e armazenamento de sessões
• Memcached (zeltro-memcached) - Camada de cache adicional
• MailHog (zeltro-mailhog) - Teste e depuração de e-mails (captura os e-mails enviados)

Opcionais — ativados automaticamente quando um projeto precisa de um, ou com zeltro enable-service:

• MariaDB (zeltro-mariadb), PostgreSQL (zeltro-postgres), MongoDB (zeltro-mongo)
• phpMyAdmin, Adminer, mongo-express, RedisInsight - Interfaces de administração de bancos de dados
• MinIO (armazenamento compatível com S3, servido pelo Silo, o fork mantido do MinIO), Meilisearch (busca de texto completo)

Estrutura de projetos#

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

Configuração de rede#

Cada projeto recebe:

• Um endereço IP Docker exclusivo (10.x.x.x) na rede zeltro-cli_vpc
• Um nome que é resolvido na rede compartilhada, de dentro de qualquer contêiner
• Uma porta externa mapeada para acesso pela LAN
• URL local: o IP do contêiner, por exemplo http://10.247.177.219
• URL na LAN: http://your-ip:port

Desinstalação#

Desinstalação por plataforma#

🐧 Linux e 🍎 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

Se você instalou o pacote .deb, rode zeltro uninstall e depois sudo apt remove zeltro-cli.

O que é removido#

O zeltro uninstall remove:

• ✅ Todos os contêineres de serviço do Zeltro (mariadb, redis, postgres etc.)
• ✅ Todos os contêineres dos projetos
• ✅ As imagens Docker (opcional, com --delete-images)
• ✅ Os volumes e redes Docker com o prefixo zeltro-cli_ — inclusive os dados dos bancos de dados compartilhados
• ✅ O binário e os arquivos-fonte do Zeltro CLI
• ✅ Faz backup dos arquivos docker-compose.yaml dos projetos como docker-compose.yaml.backup

O que é preservado:

• ✅ O código-fonte e os arquivos dos seus projetos
• ✅ A configuração em /etc/zeltro-cli (uma reinstalação a aproveita)
• ✅ Outros contêineres e imagens Docker que não são do Zeltro
• ✅ O próprio Docker Desktop/Engine

Veja as Opções de desinstalação para as flags.

🔧 Configuração#

Configuração inicial#

# Run the configuration wizard
zeltro configure

O zeltro configure também instala o autocompletar com tab do bash (em /usr/share/bash-completion/completions/zeltro e /etc/bash_completion.d/zeltro, os que existirem). Abra um shell novo e use o tab para completar comandos, nomes de projetos e nomes de instaladores:

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

Variáveis de ambiente#

• JSON_OUTPUT=1 - O mesmo que --json-output
• NO_COLOR - Qualquer valor: o mesmo que --no-colors
• FORCE_COLOR=1 - Mantém a cor quando a saída é redirecionada ou passa por um pipe (ali ela fica desligada por padrão), por exemplo zeltro status | less -R
• DEBUG_LOG_PATH - Onde o --debug escreve (padrão /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 - substituições de IA por sessão (veja "Substituições de IA por sessão" em Gerenciamento do sistema)
• ZELTRO_AI_UNATTENDED=1 / 0 - Só nesta execução: 1 roda o agente sem pedidos de aprovação, 0 os liga mesmo que a configuração dele diga o contrário (sem definir: a configuração dele decide). ZELTRO_AI_AUTO_APPROVE=1 é a forma antiga de 1
• ZELTRO_BUS_DIR - Fila de mensagens dos agentes (padrão ~/.zeltro/bus)

O diretório de projetos não é uma variável de ambiente: é o PROJECTS_DIR em /etc/zeltro-cli/.env, definido com zeltro configure --projects-dir.

📝 Observações importantes#

• Diretório exigido: as ferramentas de projeto (composer, art, wp, drush, php, npm, npx, node, python, pip, shell, django, exec, db-refresh, cache-refresh, supervisor) e ai / send precisam ser executadas de dentro de um diretório de projeto
• Saída JSON: use --json-output para integração programática (interface gráfica, scripts, automação)
• Modo não interativo: os comandos recebem argumentos explícitos e nunca mostram menus de escolha. configure e create só perguntam em um terminal; use configure --non-interactive ou create --one-off em scripts
• Criação de bancos de dados: os bancos de dados são criados e configurados automaticamente para cada projeto, e o serviço compartilhado do motor é ativado se ainda não estiver
• Endereçamento: cada projeto recebe um IP de contêiner e uma porta publicada; nada é escrito no /etc/hosts

🚦 Obtendo ajuda#

# Show comprehensive help
zeltro help

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

🔍 Solução de problemas#

Problemas comuns#

1. Serviços não iniciam: verifique se o Docker está rodando e se as portas estão livres
2. Erros de permissão: confira se o usuário está no grupo docker
3. Conexão com o banco de dados: verifique se o serviço de banco de dados está rodando com zeltro status e, se não estiver, ative-o com zeltro enable-service <mysql|postgres|mongo>
4. Conflitos de porta: cada projeto recebe automaticamente uma porta exclusiva

Comandos de depuração#

# 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 depuração#

Os principais comandos de projeto e de serviço aceitam a flag --debug (veja Opções globais), que grava logs detalhados para ajudar a resolver problemas:

• Local do log: /tmp/zeltro-cli-debug.log
• Acompanhamento por sessão: cada comando novo cria uma sessão de depuração nova
• Saída detalhada: mostra o fluxo dos scripts, as chamadas de funções e os códigos de saída
• Acompanhamento entre scripts: a flag de depuração é repassada entre os scripts automaticamente

Exemplo:

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

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

Veja Automação e JSON para saber quais comandos suportam JSON e como escrever scripts com eles.

Achou um erro nesta tradução? Avise a gente no GitHub.