CLI reference

Every acropolis command and flag with its default, plus environment variables, output, events, info.json and exit codes.

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

Commands: build, plan, inspect, cache, prewarm and gc. acropolis <command> --help lists the flags of one command. The binary also has hidden commands for the project’s own benchmark and e2e harness (bench, report, e2e); they are not covered here and are not a stable interface.

Global flags

Global flags go before or after the command.

flag	default	environment	what it does
`--events MODE`	`human`		`human`: readable progress lines on stderr. `json`: one JSON event per stderr line. `quiet`: no events. See Events.
`--home DIR`	`$XDG_CACHE_HOME/acropolis`, else `$HOME/.cache/acropolis`	`ACROPOLIS_HOME`	Store, toolchains, image rootfs and per-app caches.
`--mirror REGISTRY=MIRROR`	none	`ACROPOLIS_MIRRORS`	Registry mirror, such as `docker.io=mirror.example.com`. Repeatable or comma-separated.

build

Builds the app in a directory and writes the image. Needs root.

acropolis build [DIR] [options]

argument or flag	default	what it does
`DIR`	`.`	App directory.
`-t`, `--tag REF`	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 when the build fails. See info.json.
`-e`, `--env KEY=VALUE`	none	App variable. Repeatable. `KEY` cannot be empty; the value can. See Configuration.
`--config FILE`	`acropolis.json`, else `railpack.json`	Config file, relative to the app directory and inside it. Same as `-e ACROPOLIS_CONFIG_FILE=FILE`.
`--compression CODEC`	`zstd`	Layer compression: `zstd` (`zst`), `gzip` (`gz`) or `none` (`tar`). Use `gzip` for runtimes older than Docker 23 or containerd 1.5.
`--level N`	`0` (codec default)	Compression level. For gzip, values above 9 are rejected.
`--hermetic on\|off`	`on`	`off` runs host steps as plain host processes, with no namespaces, seccomp filter or read-only filesystem; host steps the plan marks as offline (such as Go and Rust builds) then fail. Steps inside an official image’s rootfs keep their isolation either way. With `on`, the build fails if the host cannot create network namespaces.
`--concurrency N`	`64`	Parallel downloads. Must be at least 1.
`--keep-work`	off	Keep the work directory after the build, for debugging.

Output on stdout, unless --events json: REF@DIGEST with -t, otherwise DIGEST. With --events json the build_finished event carries image and digest.

plan

Prints what build would do without building: provider, toolchains, steps and the runtime image. Runs without root.

acropolis plan [DIR] [options]

argument or flag	default	what it does
`DIR`	`.`	App directory.
`-e`, `--env KEY=VALUE`	none	App variable, as in `build`. Repeatable.
`--json`	off	Print the plan as JSON instead of text.

plan has no --config: to plan with the config file a build gets through --config FILE, pass -e ACROPOLIS_CONFIG_FILE=FILE.

--json prints one pretty-printed object on stdout with the keys app, provider, facts (detected facts such as framework or package-manager), steps (each with id, name, action and deps), image (layers, workdir, env, cmd, entrypoint, ports, user), warnings and hash. The repo keeps the plan of each of the 131 Railpack examples in tests/plans as examples.

inspect

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

acropolis inspect node:22-bookworm-slim

argument	what it does
`REFERENCE`	Image reference. Required.

cache

Exports or imports the per-app cache as a tar.zst, to keep it between ephemeral builders.

acropolis cache export FILE --key KEY
acropolis cache import FILE --key KEY

argument or flag	default	what it does
`export` or `import`		Action. Required.
`FILE`		Cache file to write or read. Required.
`--key KEY`	`ACROPOLIS_CACHE_KEY`	Per-app cache key. Required, and cannot be empty. Must match the key the build used, with the same home.

Output on stdout: cache KEY: exported 12.3 MB to FILE in 1.2s (or imported ... from FILE).

prewarm

Downloads toolchains into the home ahead of time.

acropolis prewarm [--tools LIST]

flag	default	what it does
`--tools LIST`	`node:lts,node:22,node:24,go:latest,bun:latest,uv:latest`	Comma-separated `tool:version` list. A tool without a version means `latest`. `python` is accepted.

gc

Trims the home down to a size.

acropolis gc --max-size SIZE

flag	default	what it does
`--max-size SIZE`		Target size. Required. A number with an optional `K`, `M`, `G` or `T` suffix (powers of 1024), such as `20G`.

Entries in use by running builds are kept; while builds run, only entries idle for over an hour are removed. Output on stdout: gc: 25.10 GB -> 19.80 GB, 312 entries removed, with (builds running: only entries idle for over 1h) when other builds were running.

Environment variables

Read from the environment of the acropolis process. App settings (ACROPOLIS_BUILD_CMD, ACROPOLIS_NODE_VERSION and the rest) are in Configuration.

variable	what it does
`ACROPOLIS_HOME`	Same as `--home`.
`ACROPOLIS_MIRRORS`	Same as `--mirror`, comma-separated.
`ACROPOLIS_CACHE_KEY`	Per-app cache key for `build`, and the default `--key` of `cache`. Without it, a build uses a hash of the app path. Characters other than letters, digits, `-` and `_` become `_` in the cache directory name, so `team/app` and `team_app` share a cache: keep keys unique after that.
`ACROPOLIS_CACHE_MAX`	After each build, trim the home to this size, like `gc`.
`ACROPOLIS_NO_CACHE`	Build without the per-app cache.
`ACROPOLIS_BUILD_TIMEOUT`	Whole-build timeout; 1 h by default.
`ACROPOLIS_STEP_TIMEOUT`	Timeout for each step.
`ACROPOLIS_BUILD_ID`	Build id written in every JSON event. Generated when unset.
`ACROPOLIS_ALLOW_PRIVATE_REGISTRY`	`1` allows private hosts and `http://` for what Acropolis downloads itself.
`ACROPOLIS_REGISTRY`, `ACROPOLIS_REGISTRY_USER`, `ACROPOLIS_REGISTRY_PASSWORD`	Credentials for one registry host.
`DOCKER_CONFIG`	Directory of the Docker `config.json` whose `auths` entries are used as registry credentials; `~/.docker` by default.
`XDG_CACHE_HOME`, `HOME`	Used for the default home. Only absolute values count.

Settings in the operator settings list are ignored when they come through -e or the config file.

Events

--events controls what goes to stderr. With human, each event is a line prefixed with the seconds since start. With json, each line is one JSON object with these fields plus the event’s own:

field	meaning
`v`	Schema version, currently `1`.
`build_id`	`ACROPOLIS_BUILD_ID`, or a generated id.
`ts`	Unix time in milliseconds.
`t`	Milliseconds since the process started.
`type`	Event type, below.

`type`	fields
`build_started`	`app`
`plan_ready`	`hash`, `steps`
`step_started`	`id`, `name`
`step_finished`	`id`, `name`, `ms`
`step_failed`	`id`, `name`, `error`
`log`	`step`, `line`
`downloaded`	`what`, `bytes`, `ms`
`uploaded`	`what`, `bytes`, `skipped`
`image_pushed`	`reference`, `digest`
`stats`	`bytes_downloaded`, `bytes_uploaded`, `bytes_written`, `requests`, `peak_rss_bytes`, `children_peak_rss_bytes`
`build_finished`	`ms`, `image`, `digest`
`build_failed`	`ms`, `class`, `exit_code`, `error`

A failed run ends with build_failed. In human and quiet modes a failure also prints error: ... and error class: CLASS (exit N) on stderr; in json mode stderr has only JSON lines.

info.json

build --info FILE writes this JSON, on success and on failure:

key	meaning
`acropolisVersion`	Version of the binary.
`detectedProviders`	Detected provider, as a list (Railpack-compatible).
`resolvedPackages`	Toolchains by name, with `name`, `resolvedVersion`, `source` and, when the plan asked for one, `requestedVersion` (Railpack-compatible).
`metadata`	The plan’s facts, plus `nodePackageManager` for Node apps (Railpack-compatible).
`planHash`	Hash of the plan.
`manifestDigest`	Digest of the image manifest; `null` on failure.
`warnings`	Warnings from the plan.
`watchPaths`	Repo paths, relative to the workspace root, whose changes can change the image. `["."]` when Acropolis can’t narrow it down.
`success`	`true` or `false`.
`error`	Error message, or `null`.
`errorClass`	`user`, `infra`, `config` or `internal`, or `null`.
`exitCode`	Exit code of the failure, or `null`.

Exit codes

code	class	meaning	what to do
`0`		Success.
`1`	`user`	The app’s own build failed, including build and step timeouts.	Show the log, don’t retry.
`70`	`internal`	Acropolis bug, including a panic.	Fall back to another builder and report it.
`75`	`infra`	Infrastructure: network, registry, disk, out of memory, a step killed by a signal such as SIGKILL, or the build itself interrupted by SIGTERM or SIGINT.	Retry once.
`78`	`config`	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.

The class comes from the error: a step command that exits non-zero is user, one killed by a signal is infra; other errors are matched against known messages (network and registry errors are infra; unsupported stacks, invalid config, paths outside the app and private registries are config), and anything unrecognized is internal. These classes apply to every command. Invalid arguments are rejected by the argument parser before anything runs, with a usage message.