Befehlsreferenz

Mit zeltro --help erhalten Sie dieselbe Liste im Terminal, mit zeltro <command> --help die Hilfe zu einem einzelnen Befehl.

Befehle mit der Markierung (Projektverzeichnis) müssen Sie in einem Projektverzeichnis ausführen.

🛠️ Entwicklungswerkzeuge#

Im Projektverzeichnis ausführen

✅ Statische Analyse & Linting#

Im Projektverzeichnis ausführen; Pfade sind relativ zum Projektstamm (zum Beispiel app/Console/Commands/Foo.php)

📦 Befehle im Container ausführen#

Im Projektverzeichnis ausführen

⚡ Erweiterte Laravel-Befehle#

Im Projektverzeichnis ausführen

🐍 Erweiterte Django-Befehle#

Im Projektverzeichnis ausführen

🔧 Dienste verwalten#

Von überall ausführbar

🎛️ Prozesse verwalten#

Im Projektverzeichnis ausführen

📁 Projekte verwalten#

zeltro status gibt Adressen aus, die Sie vom Host aus öffnen können: lokal http://<container-ip> (oder http://localhost:<port> unter macOS) und aus dem LAN http://<host-lan-ip>:<port>. http://<project>/ funktioniert vom Host aus nicht, denn Projektnamen lassen sich nur innerhalb von Containern auflösen. Einen Befehl zeltro ps gibt es nicht.

⚙️ System verwalten#

Optionale gemeinsame Dienste

Nur Redis, Memcached und MailHog laufen immer. Alles andere bleibt aus, bis Sie es aktivieren, und die Liste der aktivierten Dienste steht in OPTIONAL_SERVICES in /etc/zeltro-cli/.env. zeltro new, zeltro setup und zeltro install aktivieren die Datenbank, die ein Projekt braucht, automatisch.

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

Ein Dienst gilt nur dann als aktiviert, wenn er startet und weiterläuft. Auf einem Rechner, auf dem Zeltro vor der Umbenennung installiert wurde, verschiebt zeltro migrate-names die Container auf die Namen zeltro-*.

Nachrichten an andere Agenten-Sitzungen

Wenn die Zeltro-App Agenten-Sitzungen in mehreren Projekten betreibt (auf einem Host oder auf mehreren), können diese einander Nachrichten schicken. Die App übernimmt die Zustellung über einen Spool pro Benutzer unter ~/.zeltro/bus/: Sie veröffentlicht peers.json, und send legt pro Nachricht eine JSON-Datei in outbox/ ab.

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

• Führen Sie send in Ihrem Projektverzeichnis aus; daran werden Sie als Absender erkannt.
• Ein einfaches project genügt, wenn nur eine aktive Sitzung diesen Namen trägt; sonst verwenden Sie project@host.
• Jedes Ziel muss eine aktive Sitzung sein, sonst wird nichts gesendet. Nachrichten sind auf 16 KB begrenzt.
• Bei einem einzigen Ziel ist -- optional: zeltro send blog "message".
• Exit-Code 0 heißt: in die Warteschlange gestellt. Die Nachricht erscheint im Terminal des Ziels als [Zeltro message from <you>@<host> to <targets>] ....

Die Zeltro-App um etwas bitten

Ein Agent in einer Sitzung, die die Zeltro-App gestartet hat, kann den Benutzer über das Fenster der App erreichen:

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"

Exit-Codes: 0 OK, 1 Fehler, 2 falsche Verwendung, 3 die App ist nicht verfügbar (fragen Sie stattdessen im Chat), 4 Zeitüberschreitung, 5 der Benutzer hat abgelehnt, 6 die App hat abgelehnt. secret schreibt nur in Dateien innerhalb des Projekts.

zeltro ai und zeltro resume melden der App außerdem, wann ein Durchgang endet, indem sie zeltro gui event als Hook für Claude Code, Codex und aider einsetzen. Die Hook-Flags gelten nur für diesen einen Lauf und ändern Ihre Konfigurationsdateien nicht. Bei Codex wird der Hook übersprungen, wenn Sie ein eigenes notify gesetzt haben.

Optionen von zeltro ai-set

zeltro ai-set verwaltet die globale KI-Agenten-CLI, das Modell und den API-Schlüssel, die Zeltro verwendet.

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

Unterstützte Flags:

• --agent <name> – Die KI-Agenten-CLI festlegen (codex, claude, agy, qwen, aider, opencode oder hermes). gemini funktioniert noch, ist aber veraltet: Google bietet die Gemini CLI seit dem 18.06.2026 nicht mehr für private Konten an. Nutzen Sie stattdessen agy, die Antigravity CLI, die sie ersetzt.
• --model <name> – Den Modellnamen festlegen (optional für Codex, Claude, agy, Gemini, OpenCode und Hermes; Pflicht für Qwen und Aider sowie für OpenCode und Hermes mit --api-base). OpenCode und Hermes erwarten provider/model, z. B. openai/gpt-5.4-mini.
• --api-key <key> – Den KI-API-Schlüssel festlegen (optional für Codex, Claude, agy, OpenCode und Hermes; für agy und Gemini ein Gemini-API-Schlüssel, übergeben als GEMINI_API_KEY; Pflicht für Aider). --api-key "" löscht einen gespeicherten Schlüssel.
• --api-base <url> – Einen eigenen API-Endpunkt festlegen: OpenAI-kompatibel für Codex, Qwen, Aider, OpenCode und Hermes; ein Anthropic-kompatibler Proxy für Claude. --api-base none löscht ihn.
• --allow-unattended / --no-allow-unattended – Den Agenten ohne Rückfragen zur Freigabe arbeiten lassen oder das wieder abschalten. Wird in die eigene Konfiguration des Agenten geschrieben; lassen Sie beide weg, bleibt die Einstellung unverändert. Danach richten sich Läufe im Terminal; in der Desktop-App setzt der Schalter „Arbeitet ohne Nachfragen“ jedes Projekts (standardmäßig an) sie pro Sitzung über ZELTRO_AI_UNATTENDED außer Kraft.
• --install-only – Zusammen mit --agent: die CLI dieses Agenten installieren, falls sie fehlt, ohne sie zum Standard zu machen. Schreibt nichts in Zeltros Konfiguration.
• --json-output – Das Ergebnis als JSON zurückgeben (nicht interaktiv). Für sich allein ist zeltro ai-set --json-output eine reine Abfrage: Es installiert und schreibt nichts und meldet die aktuellen Einstellungen plus "session_overrides": true, "ai_language": true und "installed_agents": [...].

Wenn Sie --agent ohne --model oder --api-base ändern, werden das alte Modell und der alte Endpunkt gelöscht.

Beispiele:

• Aktuelle KI-Einstellungen anzeigen:
  • zeltro ai-set --json-output
• Codex mit einem Modell konfigurieren:
  • zeltro ai-set --agent codex --model gpt-6-sol
• Claude mit einem Modell konfigurieren:
  • zeltro ai-set --agent claude --model opus
• Aider für Anthropic konfigurieren:
  • zeltro ai-set --agent aider --model anthropic/claude-sonnet-5 --api-key sk-ant-...
• Aider für einen lokalen Ollama-Server konfigurieren:
  • zeltro ai-set --agent aider --model openai/llama3.1 --api-key ollama --api-base http://localhost:11434/v1

KI-Einstellungen pro Sitzung überschreiben

zeltro ai, resume, create (auch mit --classify-only), clone, create-installer und update-installer nutzen den Agenten, der mit zeltro ai-set festgelegt wurde. Um für einen einzelnen Lauf einen anderen zu nutzen, setzen Sie diese Umgebungsvariablen. Sie werden nie in /etc/zeltro-cli/.env geschrieben.

Nicht gesetzt heißt „den Wert aus ai-set nutzen“; gesetzt, aber leer heißt „für diesen Lauf löschen“. Ein unbekannter Agent, eine nicht lesbare Schlüsseldatei oder ein überschreibender Agent, der nicht installiert ist, führt zu einem Fehler, bevor irgendetwas läuft, und es wird nichts installiert. Nutzen Sie vorher 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 ist der einzige unterstützte Agent ohne eigene Anmeldung. Er spricht immer direkt mit der API eines Anbieters und braucht deshalb ein Modell und einen Schlüssel.

• Der Modellname bestimmt den Anbieter: openai/gpt-6-sol, anthropic/claude-sonnet-5, gemini/gemini-2.5-pro, deepseek/deepseek-chat. Siehe die Modellliste von aider.
• Aider kennzeichnet Schlüssel nach Anbieter (--api-key openai=sk-...). Zeltro speichert den reinen Schlüssel und ergänzt die Kennzeichnung anhand des Modellpräfixes, --api-key sk-... genügt also. Ein Schlüssel, der bereits ein = enthält, wird unverändert weitergereicht.
• --api-base brauchen Sie nur für einen OpenAI-kompatiblen Server: Ollama, LM Studio, OpenRouter, vLLM. Stellen Sie dem Modell dann openai/ voran. Für die gehostete API eines Anbieters lassen Sie das Feld leer.
• Zeltro startet Aider mit --no-auto-commits, damit seine Änderungen wie bei jedem anderen Agenten in Ihrem Arbeitsverzeichnis landen, statt für Sie committet zu werden.

🤖 Projekte mit KI anlegen#

zeltro create nimmt Ihre Projektidee auf, ergänzt Zeltro-spezifische Anweisungen und übergibt den kombinierten Prompt an Ihre konfigurierte KI-CLI. Zeltro richtet die Umgebung ein, die KI baut die 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"

Mit --one-off endet der Befehl nach dem Anlegen, und die Übergabe an die KI entfällt.

Was der KI-Agent tut:

1. Ist das Framework oder der Stack unklar, fragt er nach, welches er nehmen soll, bevor er weitermacht.
2. Er führt zeltro new aus, um das Projekt anzulegen und seine Container zu starten.
3. Er liest die erzeugte .env-Datei, um die Konfiguration von Datenbank, Cache und Mail zu verstehen.
4. Er baut die App nach den Konventionen des Frameworks: Migrationen, Models, Seeder, Routen, Controller, Templates.
5. Er ergänzt die README des Projekts um die lokale URL, nützliche Befehle und gegebenenfalls die Standard-Zugangsdaten.

Passt Ihre Idee zu einer bekannten App, für die es einen Zeltro-Installer gibt (Grafana, Gitea, n8n, Portainer usw.), führt der Agent zuerst zeltro install <name> aus, sodass die App in Sekunden läuft, und nimmt dann die weiteren Anpassungen aus Ihrem Prompt vor. Sie müssen nie eine docker-compose-Datei schreiben oder wissen, auf welchem Port die App lauscht.

Die KI-CLI kann je nach Konfiguration in der Cloud oder lokal laufen. Mit zeltro ai-set wählen Sie, welcher Agent zum Einsatz kommt.

Nur klassifizieren (für GUIs und andere Oberflächen)

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

Führt nur die Klassifizierungsphase aus: ermittelt den Stack, gibt das Ergebnis aus, endet mit Exit-Code 0 und legt nichts an. Der Befehl fragt nie nach und lässt sich daher gefahrlos aus einer GUI, einem Skript oder von einem Agenten aufrufen.

Es gibt ihn, weil der normale nicht interaktive Weg (--one-off, --json-output) stillschweigend die oberste Empfehlung nimmt. Für die Automatisierung ist das in Ordnung, aber die Wahl, die ein Mensch im Menü getroffen hätte, geht dabei verloren. Eine Oberfläche, die diese Auswahl selbst anzeigen will, sollte zuerst klassifizieren, die Kandidaten zeigen und dann zeltro install <app> oder zeltro new <framework> <name> mit dem aufrufen, was der Benutzer gewählt hat.

Das JSON enthält project_name (null, wenn die Idee kein echtes Thema erkennen lässt; fragen Sie dann nach, statt etwas vorauszufüllen), recommended, customization_requested, eine vorgeschlagene database mit Begründung und candidates: zuerst Apps, das Framework zuletzt, höchstens 5. Apps tragen genau eine feste database, die der Installer vorgibt; Frameworks tragen ein Array databases mit den Engines, die sie erlauben. Bieten Sie für eine App nie eine Datenbankauswahl an. Bei einem Fehler gibt der Befehl {"action": "classify", "status": "error", "message": "..."} aus und endet mit einem Exit-Code ungleich null.

🤖 KI-Agenten-Sitzungen#

Sobald Sie Ihren globalen KI-Agenten mit zeltro ai-set festgelegt haben, können Sie aus jedem Zeltro-Projektverzeichnis einen Prompt senden:

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

Standardmäßig sendet zeltro ai einen Einzelauftrag: Der Agent bekommt den Prompt, erledigt die Arbeit und beendet sich. Der dauerhafte Projektkontext steht in der AGENTS.md des Projekts (Zeltro schreibt sie beim Anlegen), deshalb kann jeder Prompt für sich stehen. Mit --interactive (-i) erhalten Sie stattdessen eine dauerhafte Sitzung. --one-off wird aus Kompatibilitätsgründen weiterhin akzeptiert.

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

zeltro ai:

• Liest AI_AGENT, AI_MODEL, AI_API_KEY und AI_API_BASE aus /etc/zeltro-cli/.env, sofern keine ZELTRO_AI_*-Überschreibung gesetzt ist.
• Startet den Agenten mit dem Prompt (Teile in [...] kommen nur hinzu, wenn sie gesetzt sind):
  • Codex: codex exec [--model "$AI_MODEL"] "<prompt>" (Einzelauftrag) / codex [--model ...] "<prompt>" (interaktiv). Schlüssel über OPENAI_API_KEY; der Endpunkt wird als -c openai_base_url="…" übergeben, weil aktuelle Codex-Versionen OPENAI_BASE_URL ignorieren.
  • Claude: claude -p [--model "$AI_MODEL"] "<prompt>" (-p nur beim Einzelauftrag). Schlüssel über ANTHROPIC_API_KEY, Endpunkt über ANTHROPIC_BASE_URL.
  • Codex und Claude haben beide ihre --api-key-Flags entfernt; der Schlüssel wird stattdessen über die Umgebung übergeben. Zeltro prüft, ob der Schlüssel zum jeweiligen Anbieter zu passen scheint (sk- für Codex, sk-ant- für Claude). Wenn nicht, ignoriert es ihn mit einer Warnung und lässt die CLI ihre eigene Anmeldung nutzen. Ein Schlüssel für den falschen Anbieter würde sonst eine funktionierende Anmeldung durch eine ersetzen, die nicht funktionieren kann.
  • Qwen: qwen --auth-type openai [--model "$AI_MODEL"] --prompt "<prompt>" (Einzelauftrag) / -i "<prompt>" (interaktiv). Schlüssel und Endpunkt über OPENAI_API_KEY / OPENAI_BASE_URL.
  • agy (Antigravity CLI): agy [--model "$AI_MODEL"] --add-dir <projects dir> -p "<prompt>" (Einzelauftrag) / -i "<prompt>" (interaktiv). Schlüssel über GEMINI_API_KEY; solange ein Schlüssel gespeichert ist, steht "modelProvider": "gemini" in ~/.gemini/antigravity-cli/settings.json. Kein eigener Endpunkt.
  • Gemini (veraltet): gemini [--model "$AI_MODEL"] --include-directories <projects dir> --output-format text --prompt "<prompt>" (Einzelauftrag) / -i "<prompt>" (interaktiv).
  • 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>" (Einzelauftrag). Aiders --message beendet sich nach der Antwort, deshalb füttern interaktive Läufe die Sitzung stattdessen mit --load und übergeben sie dann an Sie. --no-git kommt hinzu, wenn das Verzeichnis noch kein Git-Repository ist.
  • OpenCode: opencode run [-m "$AI_MODEL"] "<prompt>" (Einzelauftrag) / opencode [-m ...] --prompt "<prompt>" (interaktiv). Der Schlüssel landet in der Variablen, die der Anbieter des Modells liest; ein Endpunkt wird in OPENCODE_CONFIG_CONTENT zu einem OpenAI-kompatiblen Anbieter namens zeltro, mit dem Modell als zeltro/<model>. Die automatische Aktualisierung ist für den Lauf abgeschaltet.
  • Hermes: hermes chat [--provider <p>] [-m <model>] --oneshot -Q -q "<prompt>" (Einzelauftrag) / hermes chat [...] -q "<prompt>" (interaktiv). Ein Modellpräfix (openai/, openrouter/, anthropic/, gemini/) wird zu --provider; ein Endpunkt nutzt --provider openai mit OPENAI_BASE_URL und OPENAI_API_KEY.
• Übergibt Flags zum Umgehen von Freigaben nur auf Anweisung. Ob ein Agent ohne Rückfrage arbeitet, steht standardmäßig in der eigenen Konfiguration des Agenten (~/.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) und wird mit zeltro ai-set --allow-unattended oder zeltro ai-unattended gesetzt. Für einen einzelnen Lauf ergänzt ZELTRO_AI_UNATTENDED=1 die Flags (die Desktop-App nutzt das für ihren Schalter pro Projekt; ZELTRO_AI_AUTO_APPROVE=1 funktioniert weiterhin), und ZELTRO_AI_UNATTENDED=0 schaltet die Freigaben stattdessen ein. Mit 1 übergibt es (--dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox, --yolo, --dangerously-skip-permissions für agy, --yolo --skip-trust für Gemini, --yes-always für Aider, --auto für OpenCode, --yolo für Hermes).

🎯 Befehlsoptionen#

Globale Optionen#

Optionen für neue Projekte#

zeltro new <framework> <name>: Framework und Name sind Pflichtargumente an fester Position. Das Framework ist eines von: laravel, kavera, octobercms, drupal, wordpress, php, fastapi, flask, django, python, express, nestjs, fastify, node, nextjs, nuxt, sveltekit, astro, hono, react, vue.

Optionen zum Klonen#

zeltro clone <mode> <repo> [name]: Der Modus ist ein Pflichtargument an erster Stelle: work-directly (klonen und das Original als Upstream behalten), fork (in Ihr GitHub-Konto forken) oder new-repo (ein neues GitHub-Repo dafür anlegen).

Komplexe Projekte: Wenn Sie ein Projekt klonen, das eine eigene docker-compose mit mehreren Diensten mitbringt (mitgelieferte Datenbank, Cache, Worker), passt Zeltro sie automatisch an: Mitgelieferte Datenbank- und Cache-Dienste werden entfernt, und ihre Umgebungsvariablen zeigen danach auf Zeltros gemeinsame Container (zeltro-postgres, zeltro-mariadb, zeltro-redis, zeltro-mongo). Der Dienst, der nach außen antwortet, bekommt eine feste VPC-IP. Der Image-Typ wirkt sich nur auf diese Compose-Anpassung aus. Die Framework-Schritte (composer install, Verdrahtung der .env, Migrationen) richten sich nach der Framework-Erkennung und laufen auch bei angepassten Projekten. Mit --no-startup prüfen Sie die angepasste Compose-Datei, bevor sie startet, mit --overwrite-env richten Sie die Verbindungseinstellungen in der .env einer vorhandenen App auf die gemeinsamen Dienste aus (der APP_KEY bleibt erhalten), und mit --no-migration überspringen Sie die Migrationen.

Optionen für die Einrichtung#

zeltro setup <project> [database]: Das optionale zweite Argument ist die Datenbank-Engine (mysql, postgres, mongo, sqlite; Standard mysql).

Optionen für den Status#

Ein namentlich angegebenes Projekt (zeltro status my-project) wird auch angezeigt, wenn es gestoppt ist.

Optionen zum Entfernen#

Standardmäßig wandern die Projektdateien in den Papierkorb, und die Datenbank sowie die Docker-Volumes des Projekts bleiben erhalten.

Optionen zum Umbenennen#

zeltro rename <project> <new-name> verweigert die Arbeit, solange im Projektordner etwas läuft (eine KI-Sitzung, ein Terminal). Schließen Sie das also zuerst. Bei einem Ordner, der mit zeltro add hinzugefügt wurde, ändert sich nur der Name des Projekts; der Ordner bleibt, wo er ist.

Optionen zum Deinstallieren#

Optionen für die Konfiguration#

zeltro configure können Sie gefahrlos erneut ausführen: Die Werte aus /etc/zeltro-cli/.env bleiben als Standardwerte erhalten, und über die Abfragen können Sie sie ändern. Zeltro schreibt nicht in /etc/hosts.

💡 Anwendungsbeispiele#

Projekte klonen und einrichten#

# 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

Entwicklung mit 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

JSON-Ausgabe für die Automatisierung#

# 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

Die Adressfelder lesen

Jedes Projekt in zeltro status --json-output enthält mehrere Adressfelder. Sie bedeuten Verschiedenes, und eines davon wird leicht falsch verwendet:

Dienste verwalten#

# 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

Fortgeschrittene Nutzung#

Entwicklungsbefehle im Container

PHP-Projekte: zeltro composer, zeltro art, zeltro php, zeltro wp und zeltro drush laufen im Container Ihres Projekts mit der richtigen PHP-Umgebung:

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

Node.js-Projekte: zeltro npm, zeltro npx und zeltro node laufen im Container Ihres Projekts mit 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

Python-Projekte (FastAPI, Django, reines Python): zeltro python und zeltro pip laufen im Container Ihres Projekts:

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

Django-Projekte: Nutzen Sie die zeltro django-Wrapper für manage.py-Aufgaben:

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

Interaktive Shells und REPLs

zeltro shell öffnet automatisch die passende interaktive Umgebung für das aktuelle Projekt:

# 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

Alles, was es nicht erkennt, bekommt eine Bash-Shell. zeltro tinker bleibt als ausdrücklicher Alias nur für Laravel erhalten.

Die NestJS-REPL (src/repl.ts) wird standardmäßig nicht angelegt. Legen Sie sie nach der NestJS-REPL-Dokumentation an, dann nutzt zeltro shell sie automatisch.

🔌 Anbindung per JSON-API#

Zeltro liefert saubere JSON-Ausgabe für die programmatische Anbindung, ideal für GUI-Anwendungen und Automatisierungsskripte:

// 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"
}

Befehle mit JSON-Ausgabe#

✅ Mit JSON-Unterstützung:

• zeltro status --json-output - Status von Projekten und Diensten
• zeltro new --json-output - Bestätigung der Projekterstellung
• zeltro clone --json-output - Bestätigung des Klonens
• zeltro setup --json-output - Bestätigung der Einrichtung
• zeltro remove --json-output - Bestätigung des Entfernens
• zeltro up --json-output - Bestätigung des Projektstarts
• zeltro down --json-output - Bestätigung des Projektstopps
• zeltro start-services --json-output - Bestätigung des Dienststarts
• zeltro stop-services --json-output - Bestätigung des Dienststopps
• zeltro enable-service / disable-service --json-output - Ergebnis des Umschaltens (ohne Namen: Liste der optionalen Dienste)
• zeltro configure --json-output - Bestätigung der Konfiguration
• zeltro uninstall --json-output - Bestätigung der Deinstallation
• zeltro ai-set --json-output - Aktuelle KI-Einstellungen (für sich allein nur lesend)
• zeltro create --classify-only --json-output - Klassifizierung des Stacks
• zeltro peers --json-output / zeltro send --json-output - Agenten-Sitzungen / Ergebnis des Sendens
• zeltro get-metadata --json-output - Alle x-metadata-Schlüssel, einschließlich der vollständigen idea (status meldet nur has_idea)
• zeltro set-metadata, zeltro disable, zeltro enable --json-output - Ergebnis
• zeltro projects-dir --json-output, zeltro version --json-output

❌ Ohne JSON-Unterstützung (Container-Befehle):

• zeltro composer - Läuft im Container
• zeltro art - Läuft im Container
• zeltro wp - Läuft im Container
• zeltro drush - Läuft im Container
• zeltro php - Läuft im Container
• zeltro npm - Läuft im Container
• zeltro npx - Läuft im Container
• zeltro node - Läuft im Container
• zeltro python - Läuft im Container
• zeltro pip - Läuft im Container
• zeltro shell - Läuft im Container
• zeltro django - Läuft im Container
• zeltro exec - Läuft im Container
• zeltro exec-root - Läuft im Container
• zeltro supervisor - Läuft im Container
• zeltro redis - Direkte Verbindung zum Dienst
• zeltro memcache - Direkte Verbindung zum Dienst

🏗️ Architektur#

Enthaltene Dienste#

Laufen immer:

• Redis (zeltro-redis) - Caching und Sitzungsspeicher
• Memcached (zeltro-memcached) - Zusätzliche Cache-Schicht
• MailHog (zeltro-mailhog) - E-Mails testen und debuggen (fängt ausgehende E-Mails ab)

Optional, automatisch aktiviert, wenn ein Projekt einen davon braucht, oder mit zeltro enable-service:

• MariaDB (zeltro-mariadb), PostgreSQL (zeltro-postgres), MongoDB (zeltro-mongo)
• phpMyAdmin, Adminer, mongo-express, RedisInsight - Admin-Oberflächen für Datenbanken
• MinIO (S3-kompatibler Speicher, bereitgestellt von Silo, dem gepflegten MinIO-Fork), Meilisearch (Volltextsuche)

Projektstruktur#

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

Netzwerkkonfiguration#

Jedes Projekt bekommt:

• Eine eigene Docker-IP-Adresse (10.x.x.x) im Netzwerk zeltro-cli_vpc
• Einen Namen, der sich im gemeinsamen Netzwerk aus jedem Container heraus auflösen lässt
• Einen zugeordneten externen Port für den Zugriff aus dem LAN
• Lokale URL: die Container-IP, z. B. http://10.247.177.219
• LAN-URL: http://your-ip:port

Deinstallation#

Deinstallation je nach Plattform#

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

Wenn Sie das .deb-Paket installiert haben, führen Sie zeltro uninstall und danach sudo apt remove zeltro-cli aus.

Was entfernt wird#

zeltro uninstall entfernt:

• ✅ Alle Container der Zeltro-Dienste (mariadb, redis, postgres usw.)
• ✅ Alle einzelnen Projekt-Container
• ✅ Docker-Images (optional mit --delete-images)
• ✅ Docker-Volumes und -Netzwerke mit dem Präfix zeltro-cli_, einschließlich der Daten der gemeinsamen Datenbanken
• ✅ Das Zeltro-CLI-Binary und die Quelldateien
• ✅ Sichert die docker-compose.yaml-Dateien der Projekte als docker-compose.yaml.backup

Was erhalten bleibt:

• ✅ Der Quellcode und die Dateien Ihrer Projekte
• ✅ Die Konfiguration in /etc/zeltro-cli (eine Neuinstallation übernimmt sie)
• ✅ Andere Docker-Container und -Images, die nicht zu Zeltro gehören
• ✅ Docker Desktop/Engine selbst

Die Flags finden Sie unter Optionen zum Deinstallieren.

🔧 Konfiguration#

Ersteinrichtung#

# Run the configuration wizard
zeltro configure

zeltro configure installiert außerdem die Tab-Vervollständigung für Bash (nach /usr/share/bash-completion/completions/zeltro und /etc/bash_completion.d/zeltro, je nachdem, was vorhanden ist). Öffnen Sie eine neue Shell und vervollständigen Sie Befehle, Projektnamen und Installer-Namen mit Tab:

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

Umgebungsvariablen#

• JSON_OUTPUT=1 - Wie --json-output
• NO_COLOR - Beliebiger Wert: wie --no-colors
• FORCE_COLOR=1 - Farbe behalten, wenn die Ausgabe per Pipe oder Umleitung weitergeht (dort ist sie standardmäßig aus), z. B. zeltro status | less -R
• DEBUG_LOG_PATH - Wohin --debug schreibt (Standard /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 - KI-Einstellungen pro Sitzung überschreiben (siehe „KI-Einstellungen pro Sitzung überschreiben“ unter System verwalten)
• ZELTRO_AI_UNATTENDED=1 / 0 - Nur für diesen Lauf: 1 lässt den Agenten ohne Freigabeabfragen arbeiten, 0 schaltet sie ein, auch wenn seine Konfiguration etwas anderes sagt (nicht gesetzt: Es gilt seine Konfiguration). ZELTRO_AI_AUTO_APPROVE=1 ist die ältere Schreibweise von 1
• ZELTRO_BUS_DIR - Spool für Agenten-Nachrichten (Standard ~/.zeltro/bus)

Das Projektverzeichnis ist keine Umgebungsvariable: Es steht als PROJECTS_DIR in /etc/zeltro-cli/.env und wird mit zeltro configure --projects-dir gesetzt.

📝 Wichtige Hinweise#

• Verzeichnis: Die Projektwerkzeuge (composer, art, wp, drush, php, npm, npx, node, python, pip, shell, django, exec, db-refresh, cache-refresh, supervisor) sowie ai / send müssen in einem Projektverzeichnis ausgeführt werden
• JSON-Ausgabe: Nutzen Sie --json-output für die programmatische Anbindung (GUI, Skripte, Automatisierung)
• Nicht interaktiver Modus: Befehle nehmen ausdrückliche Argumente und zeigen nie eine Auswahl an. configure und create fragen nur in einem Terminal nach; nutzen Sie in Skripten configure --non-interactive oder create --one-off
• Datenbanken: Für jedes Projekt wird automatisch eine Datenbank angelegt und konfiguriert, und der gemeinsame Dienst der Engine wird aktiviert, falls er es noch nicht ist
• Adressen: Jedes Projekt bekommt eine Container-IP und einen veröffentlichten Port; in /etc/hosts wird nichts geschrieben

🚦 Hilfe bekommen#

# Show comprehensive help
zeltro help

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

🔍 Fehlerbehebung#

Häufige Probleme#

1. Dienste starten nicht: Prüfen Sie, ob Docker läuft und die Ports frei sind
2. Berechtigungsfehler: Stellen Sie sicher, dass der Benutzer in der Gruppe docker ist
3. Datenbankverbindung: Prüfen Sie mit zeltro status, ob der Datenbankdienst läuft, und aktivieren Sie ihn mit zeltro enable-service <mysql|postgres|mongo>, falls nicht
4. Portkonflikte: Jedes Projekt bekommt automatisch einen eigenen Port zugewiesen

Befehle zur Fehlersuche#

# 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

Debug-Modus#

Die wichtigsten Projekt- und Dienstbefehle akzeptieren ein Flag --debug (siehe Globale Optionen), das ausführliche Protokolle zur Fehlersuche schreibt:

• Speicherort des Protokolls: /tmp/zeltro-cli-debug.log
• Sitzungen: Jeder neue Befehl beginnt eine neue Debug-Sitzung
• Ausführliche Ausgabe: Zeigt den Ablauf der Skripte, Funktionsaufrufe und Exit-Codes
• Über Skripte hinweg: Das Debug-Flag wird automatisch zwischen den Skripten weitergereicht

Beispiel:

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

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

Unter Automatisierung & JSON erfahren Sie, welche Befehle JSON unterstützen und wie Sie Skripte dafür schreiben.

Einen Fehler in dieser Übersetzung gefunden? Sagen Sie es uns auf GitHub.