Automation, JSON and troubleshooting

---

No interactive prompts

Every command except zeltro configure fails with a clear “required argument” error rather than prompting. Nothing ever blocks a script or an agent waiting for input.

Use zeltro up-all / zeltro down-all to act on every project rather than looping.

---

JSON output

--json-output produces clean machine-readable output for GUIs and scripts.

zeltro status --json-output
zeltro new laravel myapp --version 11.x --json-output

{
  "action": "new_project",
  "project_name": "myapp",
  "framework": "laravel",
  "database": "mysql",
  "status": "success"
}

Scripting examples:

# wait for the database to be up
if zeltro status --json-output | jq -r '.shared_services.mariadb.status' | grep -q RUNNING; then
    echo "Database is ready"
fi

# start every project, including stopped ones
for project in $(zeltro status --all --json-output | jq -r '.projects[].name'); do
    zeltro up "$project" --json-output
done

Which commands support it

Supported: status, new, clone, setup, remove, up, down, start-services, stop-services, configure, uninstall.

Not supported — anything that runs inside a container or connects straight to a service: composer, art, wp, php, npm, npx, node, python, pip, shell, django, exec, supervisor, redis, memcache.

If you are an AI agent, never use --json-output. It suppresses all human-readable output including the success/failure distinction, so you cannot tell whether a command actually worked. It exists for external programs that parse Zeltro’s output, not for agents driving the CLI.

---

Debugging

zeltro new laravel test-project --debug
tail -f /tmp/zeltro-cli-debug.log

--debug works on every command. Each invocation starts a fresh session and logs script flow, function calls and exit codes across scripts.

---

Troubleshooting

Symptom	Check
Services won’t start	Docker is running; you’re in the docker group (log out and back in after install)
Permission errors	Same — docker group membership needs a fresh login
Can’t reach http://project/	zeltro status <project>; then docker logs <project-name>
Database connection refused	zeltro status — is the shared service running?
Project 502s after a restart	A dependency isn’t in the base image. See Architecture → Base images
Fedora: permission denied on project files	SELinux — re-run zeltro configure to relabel. See Installation
Arch: Docker won’t start after install	The system upgrade replaced the running kernel — reboot

Useful probes:

zeltro status                       # everything
zeltro status <project> --all       # include stopped projects
docker logs <project-name>
zeltro exec "ping zeltro-mariadb"   # networking from inside the container

---

Graphics tooling

The installers ship ImageMagick (convert, magick) and rsvg-convert on the host, so projects needing graphics have no extra dependencies.

Prefer generating SVG — browsers render it perfectly and it’s text an agent can write directly. Convert only when a raster is genuinely required:

rsvg-convert sprite.svg -o sprite.png                        # best SVG → PNG fidelity
convert -size 1200x800 gradient:'#1e3a8a-#04081d' bg.png     # procedural backgrounds

These are host tools — run them directly, not through zeltro exec.