Referencia de la CLI

Todos los comandos y flags de acropolis con su valor por defecto, más variables de entorno, salida, eventos, info.json y códigos de salida.

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

Comandos: build, plan, inspect, cache, prewarm y gc. acropolis <command> --help lista los flags de un comando. El binario también tiene comandos ocultos para el benchmark y el harness e2e del propio proyecto (bench, report, e2e); no se cubren acá y no son una interfaz estable.

Flags globales

Los flags globales van antes o después del comando.

flag	valor por defecto	entorno	qué hace
`--events MODE`	`human`		`human`: líneas de progreso legibles en stderr. `json`: un evento JSON por línea de stderr. `quiet`: sin eventos. Mirá Eventos.
`--home DIR`	`$XDG_CACHE_HOME/acropolis`, si no `$HOME/.cache/acropolis`	`ACROPOLIS_HOME`	Store, toolchains, rootfs de imágenes y cachés por app.
`--mirror REGISTRY=MIRROR`	ninguno	`ACROPOLIS_MIRRORS`	Mirror de un registry, como `docker.io=mirror.example.com`. Se puede repetir o separar con comas.

build

Construye la app de un directorio y escribe la imagen. Necesita root.

acropolis build [DIR] [options]

argumento o flag	valor por defecto	qué hace
`DIR`	`.`	Directorio de la app.
`-t`, `--tag REF`	ninguno	Sube la imagen a esta referencia.
`--oci FILE`	ninguno	Escribe un tar con layout de imagen OCI que aceptan `docker load`, `skopeo` y `regctl image import`.
`--info FILE`	ninguno	Escribe un resumen en JSON, también cuando el build falla. Mirá info.json.
`-e`, `--env KEY=VALUE`	ninguno	Variable de la app. Se puede repetir. `KEY` no puede estar vacía; el valor sí. Mirá Configuración.
`--config FILE`	`acropolis.json`, si no `railpack.json`	Archivo de configuración, relativo al directorio de la app y dentro de él. Igual que `-e ACROPOLIS_CONFIG_FILE=FILE`.
`--compression CODEC`	`zstd`	Compresión de las capas: `zstd` (`zst`), `gzip` (`gz`) o `none` (`tar`). Usá `gzip` para runtimes anteriores a Docker 23 o containerd 1.5.
`--level N`	`0` (el del códec)	Nivel de compresión. Para gzip, se rechazan valores mayores a 9.
`--hermetic on\|off`	`on`	`off` corre los pasos del host como procesos comunes del host, sin namespaces, sin filtro seccomp y sin sistema de archivos de solo lectura; en ese caso, los pasos del host que el plan marca como offline (como los builds de Go y Rust) fallan. Los pasos dentro del rootfs de una imagen oficial conservan su aislamiento en los dos casos. Con `on`, el build falla si el host no puede crear namespaces de red.
`--concurrency N`	`64`	Descargas en paralelo. Tiene que ser al menos 1.
`--keep-work`	desactivado	Conserva el directorio de trabajo después del build, para depurar.

Salida en stdout, salvo con --events json: REF@DIGEST con -t, si no DIGEST. Con --events json, el evento build_finished lleva image y digest.

plan

Muestra lo que haría build sin construir nada: provider, toolchains, pasos y la imagen de runtime. Corre sin root.

acropolis plan [DIR] [options]

argumento o flag	valor por defecto	qué hace
`DIR`	`.`	Directorio de la app.
`-e`, `--env KEY=VALUE`	ninguno	Variable de la app, como en `build`. Se puede repetir.
`--json`	desactivado	Muestra el plan como JSON en vez de texto.

plan no tiene --config: para planificar con el archivo de configuración que un build recibe por --config FILE, pasá -e ACROPOLIS_CONFIG_FILE=FILE.

--json imprime en stdout un objeto formateado con las claves app, provider, facts (datos detectados como framework o package-manager), steps (cada uno con id, name, action y deps), image (layers, workdir, env, cmd, entrypoint, ports, user), warnings y hash. El repo guarda como ejemplos el plan de cada uno de los 131 ejemplos de Railpack en tests/plans.

inspect

Resuelve una referencia de imagen para la plataforma del host e imprime un JSON con reference, digest, manifest y config.

acropolis inspect node:22-bookworm-slim

argumento	qué hace
`REFERENCE`	Referencia de la imagen. Obligatorio.

cache

Exporta o importa la caché por app como tar.zst, para conservarla entre builders efímeros.

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

argumento o flag	valor por defecto	qué hace
`export` o `import`		Acción. Obligatorio.
`FILE`		Archivo de caché a escribir o leer. Obligatorio.
`--key KEY`	`ACROPOLIS_CACHE_KEY`	Clave de caché por app. Obligatoria, y no puede estar vacía. Tiene que coincidir con la clave que usó el build, con el mismo home.

Salida en stdout: cache KEY: exported 12.3 MB to FILE in 1.2s (o imported ... from FILE).

prewarm

Descarga toolchains en el home por adelantado.

acropolis prewarm [--tools LIST]

flag	valor por defecto	qué hace
`--tools LIST`	`node:lts,node:22,node:24,go:latest,bun:latest,uv:latest`	Lista de `tool:version` separada por comas. Una herramienta sin versión significa `latest`. Se acepta `python`.

gc

Recorta el home hasta un tamaño.

acropolis gc --max-size SIZE

flag	valor por defecto	qué hace
`--max-size SIZE`		Tamaño objetivo. Obligatorio. Un número con un sufijo opcional `K`, `M`, `G` o `T` (potencias de 1024), como `20G`.

Las entradas que usan builds en curso se conservan; mientras hay builds corriendo, solo se borran las entradas sin uso por más de una hora. Salida en stdout: gc: 25.10 GB -> 19.80 GB, 312 entries removed, con (builds running: only entries idle for over 1h) cuando había otros builds corriendo.

Variables de entorno

Se leen del entorno del proceso acropolis. Los ajustes de la app (ACROPOLIS_BUILD_CMD, ACROPOLIS_NODE_VERSION y el resto) están en Configuración.

variable	qué hace
`ACROPOLIS_HOME`	Igual que `--home`.
`ACROPOLIS_MIRRORS`	Igual que `--mirror`, separado por comas.
`ACROPOLIS_CACHE_KEY`	Clave de caché por app para `build`, y el `--key` por defecto de `cache`. Si no está, el build usa un hash de la ruta de la app. Los caracteres que no son letras, dígitos, `-` ni `_` se convierten en `_` en el nombre del directorio de caché, así que `team/app` y `team_app` comparten caché: asegurate de que las claves sigan siendo únicas después de ese reemplazo.
`ACROPOLIS_CACHE_MAX`	Después de cada build, recorta el home a este tamaño, como `gc`.
`ACROPOLIS_NO_CACHE`	Construye sin la caché por app.
`ACROPOLIS_BUILD_TIMEOUT`	Timeout de todo el build; 1 h por defecto.
`ACROPOLIS_STEP_TIMEOUT`	Timeout de cada paso.
`ACROPOLIS_BUILD_ID`	Id del build que se escribe en cada evento JSON. Se genera si no está definido.
`ACROPOLIS_ALLOW_PRIVATE_REGISTRY`	`1` permite hosts privados y `http://` para lo que Acropolis descarga por su cuenta.
`ACROPOLIS_REGISTRY`, `ACROPOLIS_REGISTRY_USER`, `ACROPOLIS_REGISTRY_PASSWORD`	Credenciales para un host de registry.
`DOCKER_CONFIG`	Directorio del `config.json` de Docker cuyas entradas de `auths` se usan como credenciales de registry; `~/.docker` por defecto.
`XDG_CACHE_HOME`, `HOME`	Se usan para el home por defecto. Solo cuentan los valores absolutos.

Los ajustes de la lista de ajustes del operador se ignoran cuando llegan por -e o por el archivo de configuración.

Eventos

--events controla qué va a stderr. Con human, cada evento es una línea con los segundos desde el inicio como prefijo. Con json, cada línea es un objeto JSON con estos campos más los propios del evento:

campo	significado
`v`	Versión del esquema, actualmente `1`.
`build_id`	`ACROPOLIS_BUILD_ID`, o un id generado.
`ts`	Tiempo Unix en milisegundos.
`t`	Milisegundos desde que arrancó el proceso.
`type`	Tipo de evento, abajo.

`type`	campos
`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`

Una ejecución fallida termina con build_failed. En los modos human y quiet, un fallo también imprime error: ... y error class: CLASS (exit N) en stderr; en modo json, stderr tiene solo líneas JSON.

info.json

build --info FILE escribe este JSON, tanto si sale bien como si falla:

clave	significado
`acropolisVersion`	Versión del binario.
`detectedProviders`	Provider detectado, como lista (compatible con Railpack).
`resolvedPackages`	Toolchains por nombre, con `name`, `resolvedVersion`, `source` y, cuando el plan pidió una, `requestedVersion` (compatible con Railpack).
`metadata`	Los datos del plan, más `nodePackageManager` para apps de Node (compatible con Railpack).
`planHash`	Hash del plan.
`manifestDigest`	Digest del manifiesto de la imagen; `null` si falla.
`warnings`	Advertencias del plan.
`watchPaths`	Rutas del repo, relativas a la raíz del workspace, cuyos cambios pueden cambiar la imagen. `["."]` cuando Acropolis no puede acotarlo.
`success`	`true` o `false`.
`error`	Mensaje de error, o `null`.
`errorClass`	`user`, `infra`, `config` o `internal`, o `null`.
`exitCode`	Código de salida del fallo, o `null`.

Códigos de salida

código	clase	significado	qué hacer
`0`		Éxito.
`1`	`user`	Falló el build propio de la app, incluidos los timeouts de build y de paso.	Mostrá el log, no reintentes.
`70`	`internal`	Bug de Acropolis, incluido un panic.	Pasá a otro builder y reportalo.
`75`	`infra`	Infraestructura: red, registry, disco, falta de memoria, un paso matado por una señal como SIGKILL, o el propio build interrumpido por SIGTERM o SIGINT.	Reintentá una vez.
`78`	`config`	La app no se puede construir tal como está configurada: stack o configuración no soportados, rutas fuera de la app, registries privados.	Pasá a otro builder o mostrá el error.

La clase sale del error: un comando de un paso que termina con un código distinto de cero es user, y uno matado por una señal es infra; los demás errores se comparan con mensajes conocidos (los errores de red y de registry son infra; los stacks no soportados, la configuración inválida, las rutas fuera de la app y los registries privados son config), y todo lo que no se reconoce es internal. Estas clases aplican a todos los comandos. El parser de argumentos rechaza los argumentos inválidos antes de que corra nada, con un mensaje de uso.