Reading neo caddy routes and Repairing Drift with neo caddy reload

Caddy has no config reload

Every Neo command that touches routing (neo domain, neo deploy, basic_auth changes) talks to Caddy's admin API directly — changes apply the instant they're made. There's no separate "reload" step in a healthy setup, which means neo caddy update doesn't mean what it sounds like: it updates the Caddy image (pull + recreate), not the routes.

Seeing what's actually being served

neo caddy routes

ROUTE ID    DOMAINS              AUTH     UPSTREAMS
app-shop    shop.example.com     basic    app-shop:8080
app-api     api.example.com      none     app-api:8080

This reads the routes back out of the running Caddy — not out of .neo.yml, not out of server state, but what the proxy is genuinely serving right now. It's the one place that can tell a route that was configured from a route that was actually accepted, which matters because with basic_auth the reverse_proxy handler sits nested inside a subroute behind an authentication handler — a stale chain that dropped auth looks identical from the outside otherwise.

Repairing drift

neo caddy reload             # every app
neo caddy reload --app shop  # just one

Rewrites the route for each app from /etc/neo/state.json — domains, upstream, HTTP/HTTPS mode, basic auth, edge-HTTPS headers — without a redeploy. Use it after an interrupted deploy, a manual Docker change, or if you're ever unsure whether the live proxy matches what Neo thinks it configured.

When you'd reach for this

If neo caddy routes shows none in the AUTH column for an app that should have basic_auth, or an upstream pointing at a container that no longer exists, neo caddy reload --app <name> fixes it immediately — no image rebuild, no downtime.