CLI reference¶
Install with curl -fsSL https://allocus.dev/install | sh (or
uv tool install git+https://github.com/allocusdev/cli). Every command is run from
your app's repo unless noted.
allocus login¶
Store your API key so the CLI can act as you. Prompts for the key (hidden input) unless you pass it.
| Option | Default | Meaning |
|---|---|---|
--key |
(prompt) | API key from your dashboard. |
--url |
https://allocus.dev |
Control-plane URL. |
allocus logout¶
Forget the stored credentials.
allocus status¶
Show your account, your box (its status, health, and current load), and the apps running on it.
cli : v0.5.0
developer : you
box : you [active] · online
load : cpu 12% · mem 0.9/2.0 GB · disk 6.0/20.0 GB · load 0.80
apps : my-app, another-app
Health comes from the box's heartbeat: online (heard from in the last few
seconds), stale (gone quiet), or offline. Load is the box's current CPU,
memory, and disk use — the signal for when it's time to scale up to a larger box.
Both appear once the box has sent at least one heartbeat; the same figures (with a
short CPU history) show on your dashboard.
allocus init¶
Scaffold allocus.yaml (and a starter Dockerfile if you don't have one) in the
current directory.
| Option | Default | Meaning |
|---|---|---|
--name |
current directory name | The app's name (becomes its subdomain). |
--port |
8080 |
The port your app listens on. |
allocus schema¶
Print the full allocus.yaml field reference — every supported field for both a
single container and a multi-service stack (build, image, port, expose,
path, strip_path, environment, command, depends_on, volumes), plus the
networking and secrets rules. Handy when you're hand-writing a manifest.
See also Multi-container stacks.
allocus validate¶
Check allocus.yaml — schema and routing — without building or deploying anything.
Rejects unknown keys and reports the problem in one line.
allocus render¶
Print the Compose descriptor your manifest generates — no build, no deploy. A fast feedback loop, and the way to see the exact Traefik labels, networks, and volumes you're being handed.
When you're logged in, the app host and image refs show your real box handle
(<name>.<you>.allocus.dev becomes e.g. myapp.alice.allocus.dev), so the preview
matches what deploy produces. Logged out or offline, it falls back to <you> /
<registry> placeholders and still works.
allocus deploy¶
Build the app in the current directory, push it, and run it on your box. Reads
allocus.yaml; requires a launched box.
Prerequisite: a running Docker daemon with the Buildx plugin (both ship with
Docker Desktop). The image is built locally — cross-compiled to the box's linux/amd64
— and pushed before the box pulls it. allocus deploy checks this up front and fails
with a clear message if Docker isn't installed, Buildx is missing, or the daemon is
down, rather than erroring mid-build.
What it does: docker buildx build --platform linux/amd64 → push to your registry
namespace (tagged with the git SHA) → POST /v1/deploy. The app goes live at
https://<name>.<you>.allocus.dev. See How it works.
Add --wait to block until the box reports the app healthy (or names the
service that failed), instead of returning as soon as the deploy is queued:
allocus logs¶
Show a running app's container logs. The box is firewalled, so the CLI asks the
box's agent (via the control plane) to run docker compose logs and returns the
output — it arrives within a few seconds.
| Option | Default | Meaning |
|---|---|---|
--service |
all | Limit to one stack service (e.g. api). |
--tail |
200 |
Number of recent lines. |
allocus rollback¶
Redeploy a previous image SHA with no rebuild.
allocus apps¶
List the apps currently running on your box.
allocus remove¶
Take an app off your box. Stops and deletes its containers — which drops its Traefik route, so the URL stops resolving — and deletes its compose file from the box.
allocus remove # this repo's app (from allocus.yaml), with a prompt
allocus remove todolist --yes
allocus remove blog --keep-data # leave its named volumes (e.g. a database) in place
| Option | Default | Meaning |
|---|---|---|
--keep-data |
off | Keep the app's named volumes instead of deleting them. |
-y, --yes |
off | Skip the confirmation prompt. |
Your repo isn't touched — allocus deploy puts the app straight back. Secrets you set
with allocus secrets set are kept too, and reapply on the next deploy; use
allocus secrets rm to delete those.
The app stays listed in allocus apps until the box confirms it's actually down, so a
removal that fails (Docker wedged, box offline) leaves things as they were rather than
losing track of a container that's still serving traffic.
allocus secrets¶
Per-app secrets, encrypted at rest and delivered to your box at deploy time (written
to the app's .env, never committed). App name defaults to the name in
allocus.yaml; override with --app.
allocus secrets set DATABASE_URL=postgres://… # set (or update) a secret
allocus secrets list # names only — values never shown
allocus secrets rm DATABASE_URL # remove one
Reference them in allocus.yaml as ${NAME}, or read them as environment variables
in your containers. Changes apply on the next allocus deploy.
Configuration¶
The CLI stores its config (control-plane URL + API key) locally after
allocus login. Apps are described per-repo by allocus.yaml:
Run allocus schema for every field, or see Multi-container stacks for
the services: form.