Usage

The acropolis CLI. build, plan, cache, prewarm, inspect and gc, with their flags and exit codes.

acropolis [--events human|json|quiet] [--home DIR] [--mirror REGISTRY=MIRROR] <command>

Global flags

flag	default	what it does
`--events`	`human`	`human` prints readable lines, `json` prints one JSON event per stderr line, `quiet` prints no events.
`--home`	`$XDG_CACHE_HOME/acropolis`, else `~/.cache/acropolis`	Store, toolchains, image rootfs and per-app caches. Also `ACROPOLIS_HOME`.
`--mirror`	none	Registry mirror, `docker.io=mirror.example.com`. Repeatable or comma-separated; also `ACROPOLIS_MIRRORS`.

build

Builds the app in a directory (. by default) and writes the image.

acropolis build ./my-app -t registry.example.com/team/my-app:latest
acropolis build ./my-app --oci image.tar --info info.json -e NODE_ENV=production

flag	default	what it does
`-t`, `--tag`	none	Push the image to this reference.
`--oci FILE`	none	Write an OCI image layout tar that `docker load`, `skopeo` and `regctl image import` accept.
`--info FILE`	none	Write a JSON summary, also for failed builds.
`-e`, `--env KEY=VALUE`	none	App variable for the build. Repeatable. See Configuration.
`--config FILE`	`acropolis.json`, else `railpack.json`	Config file, relative to the app directory.
`--compression`	`zstd`	Layer compression: `zstd` or `gzip`. Use `gzip` for runtimes older than Docker 23 or containerd 1.5.
`--level`	`0` (codec default)	Compression level; 1 to 9 for gzip.
`--hermetic`	`on`	`off` runs steps without namespaces. Builds fail with `on` if the host cannot create network namespaces.
`--concurrency`	`64`	Parallel downloads.
`--keep-work`	off	Keep the work directory after the build, for debugging.

info.json carries Railpack-compatible keys (detectedProviders, resolvedPackages, metadata) plus acropolisVersion, planHash, manifestDigest, warnings, watchPaths, success, error, errorClass and exitCode.

plan

Prints what build would do, without building: detected providers, toolchains, steps and the runtime base. It runs without root.

acropolis plan ./my-app
acropolis plan ./my-app --json

Takes the same -e variables as build.

cache

Exports or imports the per-app cache (Go and Cargo builds, node_modules, .next/cache, …) as a tar.zst, to keep it between ephemeral builders.

acropolis cache import cache.tar.zst --key my-app
acropolis build ./my-app -t registry.example.com/team/my-app:latest
acropolis cache export cache.tar.zst --key my-app

--key defaults to ACROPOLIS_CACHE_KEY. A missing or broken cache file is not an error for the build: skip the import.

prewarm

Downloads toolchains into the home ahead of time, as the builder image does.

acropolis prewarm --tools node:lts,go:latest,bun:latest,uv:latest,python:3.13

The default list is node:lts,node:22,node:24,go:latest,bun:latest,uv:latest.

inspect

Resolves an image reference for the host platform and prints its digest, manifest and config as JSON.

acropolis inspect node:22-bookworm-slim

gc

Trims the home down to a size. Entries in use by running builds are kept; while builds run, only entries idle for over an hour are removed.

acropolis gc --max-size 20G

Exit codes

code	meaning	what to do
`0`	built
`1`	the app’s own build failed, including build and step timeouts	show the log, don’t retry
`70`	Acropolis bug, including a panic	fall back to another builder and report it
`75`	infrastructure: network, registry, disk, a step killed with SIGKILL, SIGTERM/SIGINT	retry once
`78`	the app cannot be built as configured: unsupported stack or config, paths outside the app, private registries	fall back to another builder or show the error

Events

With --events json each stderr line is a JSON object with v (schema version), build_id, ts, t (ms since start), type and the event’s fields. A failed build ends with type: "build_failed" carrying class, exit_code and error.