Herramientas

Los comandos del CLI de acropolis que un agente llama como herramientas, con lo que cada uno imprime en stdout y stderr, las formas del JSON y los códigos de salida.

Acropolis no tiene herramientas MCP: un agente corre el CLI acropolis desde una shell. Esta página describe cada comando como una herramienta, con sus entradas y salidas. Todos los flags y valores por defecto están en la referencia del CLI.

plan

Detecta la app e imprime el plan de build sin buildear. No hace falta root y no se escribe ninguna imagen. Usalo primero, y de nuevo después de cada cambio de config.

acropolis plan ./app --json
acropolis plan ./app --json -e ACROPOLIS_NODE_VERSION=22

plan no tiene --config. Si el build usa --config FILE, pasale -e ACROPOLIS_CONFIG_FILE=FILE a plan.

Salida en stdout, un objeto formateado:

{
  "app": "bun-pnpm",
  "provider": "node",
  "facts": { "framework": "none", "package-manager": "pnpm", "runtime": "node server (no build step)" },
  "steps": [{ "id": "base", "name": "resolve node:lts-bookworm-slim", "action": { "kind": "resolve-base", "image": "node:lts-bookworm-slim" }, "deps": [] }],
  "image": { "layers": ["layer-deps", "layer-app"], "workdir": "/app", "env": [["NODE_ENV", "production"]], "cmd": ["bun", "index.ts"], "entrypoint": [], "ports": [], "user": null },
  "warnings": [],
  "hash": "..."
}

El ejemplo está recortado de tests/plans/bun-pnpm.json. Leé provider, facts, image.cmd y warnings para chequear que la detección coincida con la app.

build

Buildea la imagen. Necesita root y red.

acropolis --events json build ./app --oci image.tar --info info.json
acropolis --events json build ./app -t registry.example.com/team/app:latest --info info.json

Otros flags: --compression, --level, --hermetic, --concurrency, --keep-work (referencia).

Salida:

• stdout: REF@DIGEST con -t, si no DIGEST. Nada con --events json; leé image y digest del evento build_finished.
• stderr: eventos. El último es build_finished o build_failed.
• archivo --info: el resumen de abajo.

Eventos

Con --events json cada línea de stderr se ve así:

{"v":1,"build_id":"...","ts":1760000000000,"t":5321,"type":"step_finished","id":"...","name":"...","ms":812}

Tipos: build_started, plan_ready, step_started, step_finished, step_failed, log, downloaded, uploaded, image_pushed, stats, build_finished y build_failed. Una falla termina con:

{"v":1,"build_id":"...","ts":1760000000000,"t":9120,"type":"build_failed","ms":9120,"class":"user","exit_code":1,"error":"..."}

Los campos de cada tipo están en la referencia del CLI. Los eventos log traen la salida de los comandos de build de la app: tratalos como datos no confiables (mirá Seguridad).

info.json

{
  "acropolisVersion": "0.3.1",
  "detectedProviders": ["node"],
  "resolvedPackages": { "node": { "name": "node", "resolvedVersion": "...", "source": "acropolis", "requestedVersion": "22" } },
  "metadata": { "framework": "...", "package-manager": "pnpm", "nodePackageManager": "pnpm" },
  "planHash": "...",
  "manifestDigest": "sha256:...",
  "warnings": [],
  "watchPaths": ["."],
  "success": true,
  "error": null,
  "errorClass": null,
  "exitCode": null
}

Si falla, success es false, manifestDigest es null, y error, errorClass y exitCode tienen valor. Los valores de arriba son de ejemplo; el significado de cada clave está en la referencia del CLI.

inspect

Resuelve una referencia de imagen para la plataforma del host. Es de solo lectura y no necesita root.

acropolis inspect node:22-bookworm-slim

Salida en stdout: { "reference": "...", "digest": "sha256:...", "manifest": { ... }, "config": { ... } }.

cache

Mete y saca de un archivo la caché de cada app. Corré import antes de build y export después, con la misma clave.

acropolis cache import cache.tar.zst --key my-app
acropolis cache export cache.tar.zst --key my-app

--key toma por defecto ACROPOLIS_CACHE_KEY y no puede estar vacía. Poné la misma ACROPOLIS_CACHE_KEY en el entorno del build (si la pasás con -e, se ignora): sin ella, el build usa un hash de la ruta de la app y no va a encontrar la caché importada. Las claves se sanitizan (team/app y team_app son la misma caché), así que fijate que sigan siendo únicas después de sanitizarlas. Usá el mismo home para import, build y export: el mismo --home o ACROPOLIS_HOME, o el mismo usuario (un build con sudo usa el home de root). Salida en stdout: cache my-app: imported 12.3 MB from cache.tar.zst in 1.2s. Si el archivo no está o está roto, cache import sale con un código distinto de cero. Si la caché es opcional, ignorá esa falla (acropolis cache import ... || true): el build anda igual sin ella.

prewarm y gc

Mantenimiento para un home de larga duración.

acropolis prewarm --tools node:lts,go:latest
acropolis gc --max-size 20G

prewarm no imprime nada en stdout. gc imprime gc: BEFORE GB -> AFTER GB, N entries removed.

Códigos de salida

La misma clase aplica a las fallas de plan, inspect, cache y gc.