Skip to content

Cache Management

AppMecca puts its edge cache in front of every service that opts in. Four commands let you inspect and manage that cache from the CLI.

Which apps have an edge cache?

A static app (type: static, and type: spa builds) is always served through the edge cache — that is the only way it is served. A container app gets one only if you add a cache: block to the service in appmecca.yaml. Without that block, nothing is cached and these commands report that there is no edge cache to manage.

When to use each command

Need Command
See whether a service has an edge cache at all mecca cache status
Flush cached content after a deploy mecca cache invalidate
Temporarily disable caching while debugging mecca cache bypass
Re-enable caching after debugging mecca cache bypass --restore

mecca cache status

Show which of an app's services sit behind an edge cache, and the state of each:

# Every service
mecca cache status myapp -e dev

# One service, with its TTL and origin
mecca cache status myapp web -e dev

If a service has no edge cache, the command says so rather than erroring — that is the normal state for a container app with no cache: block.

mecca cache invalidate

Flush cached content for a service after a deploy or fix. Most deploys already invalidate automatically (the deploy agent runs an invalidation as its last phase) — use this command when:

  • A deploy succeeded but a stale page is still being served from the edge.
  • You changed content in a bucket or on a drive and want it visible immediately.
  • A bug in the previous version is being served from cache.
# Invalidate every path on every service for an app
mecca cache invalidate myapp -e dev

# Invalidate every path on a single service
mecca cache invalidate myapp web -e dev

# Invalidate a specific path pattern
mecca cache invalidate myapp web --path "/api/*" -e dev

The service name is an optional positional argument after the app name — omit it to invalidate every cached service on the app. --path defaults to /* (everything). The command submits the invalidation and prints one line per service it touched; propagation across edge locations typically completes in 30–60 seconds.

mecca cache bypass

Temporarily disable caching so you can debug live traffic without the edge interfering. Sets every TTL to 0 — each request then reaches your origin — and saves the original settings so --restore puts them back exactly as they were.

# Bypass caching on the app
mecca cache bypass myapp -e dev

# Restore the saved settings
mecca cache bypass myapp --restore -e dev

The service name is an optional positional argument, the same as it is on invalidate. Most apps are served by a single CloudFront distribution covering every service, so "bypass service X" has nothing to act on that "bypass the app" does not — name a service and the command still acts on the whole app, and says so:

✓ Bypass enabled (TTL=0)
  Scope: app
  This app is path-routed: one CloudFront distribution fronts every service,
  so this acts on the whole app rather than on that service alone.

If your app has more than one distribution the command tells you what it did:

  • two branches — it acts on your production branch's distribution and says so. The other one is left alone, and cannot be reached from the CLI yet.
  • an older per-service layout with several services — it refuses and lists them, so you can name the one you mean.

If your app declares no cache lifetimes at all, its edge already forwards every request to your container, so there is nothing to bypass. The command says Nothing to change rather than claiming a change it did not make.

A bypass on an app that is currently private is refused: a private app's edge serves nothing, so the setting would have no effect. Publish the app first.

While bypassed:

  • Every request reaches your container — expect higher origin load.
  • The edge cache stays in front of the service, so TLS termination and the hostname are unaffected.
  • The bypass state survives across deploys until you restore it.

Changes take a couple of minutes to propagate across edge locations. If you forget to restore, mecca cache bypass <app> --restore reapplies the saved settings.

What --restore does and does not put back

--restore reverts the app's default cache behaviour to the TTLs saved when the bypass was enabled. Any path you declared under cache.behaviors: stays at TTL 0 until your next deploy rewrites it from your configuration — the command tells you this when you run it. If you need those paths back immediately, redeploy.

The command exits non-zero when the bypass fails — no distribution found, an ambiguous app, or a rejection from CloudFront — so it is safe to use in a script.

How the deploy-time invalidation differs

Every deploy runs an automatic invalidation as its final phase, controlled per-service by cache.invalidate_on_deploy in appmecca.yaml (default true when a cache: block is present). That covers the common "I just deployed and want fresh content" case without any manual command.

mecca cache invalidate is for the cases the automatic one doesn't cover: content changed outside a deploy, post-deploy hot-fixes, or apps where you set cache.invalidate_on_deploy: false to control invalidation explicitly.

Caching and private apps do not mix

A cached response is served from the edge without contacting your app or the auth gateway, so any path with a cache lifetime stays readable to anonymous visitors even after mecca app protect. See Public and Private Apps.

Next Steps