---
title: Usage
description: The acropolis CLI. build, plan, cache, prewarm, inspect and gc, with their flags and exit codes.
sidebar:
  icon: terminal
---

```bash
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.

```bash
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](/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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`.