CLI-Referenz

cloady deployt und verwaltet deine Anwendungen aus dem Terminal. Es ruft dieselbe REST-API auf, die auch das Dashboard nutzt – alles, was du per Skript erledigst, verhält sich also genau so, als würdest du dich durch die Oberfläche klicken.

Installation

npm install -g cloady

Benötigt Node 20+. Prüfe die Installation mit:

cloady --version

Authentifizierung

cloady login ohne Argumente öffnet deinen Browser, zeigt einen Code zum Bestätigen an und speichert das Token, das es zurückbekommt:

cloady login
# Confirm this code matches:  WXYZ-1234
# logged in as you@example.com

Mit --scope read, --scope deploy oder --scope full (Standard) schränkst du ein, was dieses Token darf.

Um ein selbst erstelltes Token zu verwenden, leg im Dashboard unter Account → API tokens eines an – der Wert (cldy_…) wird nur einmal angezeigt – und übergib es als Argument:

cloady login cldy_…

In beiden Fällen wird das Token in ~/.config/cloady/config.json gespeichert (Modus 0600; $XDG_CONFIG_HOME wird berücksichtigt). cloady logout entfernt es.

Reihenfolge, in der das Token ermittelt wird – der erste Treffer gewinnt:

1. Flag --token <token>
2. Umgebungsvariable CLOADY_TOKEN
3. Die gespeicherte Konfigurationsdatei

Tipp für CI: Lass login ganz weg und setz CLOADY_TOKEN in der Umgebung des Jobs.

Globale Optionen

Jeder Befehl akzeptiert:

Fehler werden als error: <code>: <message> auf stderr ausgegeben, und die CLI beendet sich mit einem Exit-Code ungleich null, sodass &&-Ketten und CI-Schritte korrekt fehlschlagen. Diese begegnen dir in der Praxis:

Aus einem Repository deployen

cloady deploy ist der einzige Befehl zum Anlegen; --type gibt an, woher der Code kommt (git, upload oder catalog).

cloady deploy github.com/your-org/your-repo --type git

Was ohne weitere Flags passiert:

• Workspace – hast du genau einen, wird er verwendet. Mehrere → eine interaktive Auswahl. Keinen → die CLI führt dich direkt dort durch das Anlegen eines Workspaces (Name und ID; ein neuer Workspace kostet nichts).
• Region – dort, wo die meisten deiner Apps schon laufen, sonst die erste Region, die bereit ist. Die Wahl der Region legt nur fest, wo diese App läuft.
• Name – der Name des Repositorys.
• Umgebung – production.

Der Build läuft auf Cloady (dein Stack wird erkannt, oder dein Dockerfile wird verwendet, wenn das Repo eines hat), und die App antwortet unter einer URL wie shop-k7q2v9ze-acme.cloady.io – gebildet aus dem Namen deiner App, einem kurzen Code und dem Namen deines Workspaces, mit fertig eingerichtetem HTTPS. Bei Preview- und Development-Apps ist die URL gleich aufgebaut; der kurze Code hält sie für jede App eindeutig.

Der Befehl kehrt zurück, sobald der Deploy startet, und gibt die App-ID, ihren Status und ihre URL aus; der Build läuft danach weiter. Private Repositorys funktionieren, sobald der Workspace mit GitHub verbunden ist (Settings → Integrations).

Flags für alle Quelltypen:

cloady deploy github.com/acme/api --type git --name api --env preview --branch develop --port 8080

Jede App läuft in einer Region und einer Umgebung, und der Name einer App ist innerhalb eines Workspaces und einer Umgebung eindeutig.

Einen lokalen Ordner deployen

Ohne --type packt cloady deploy das aktuelle Verzeichnis in eine ZIP-Datei und lädt sie hoch – ganz ohne Git-Remote:

cloady deploy                     # the current folder
cloady deploy ./services/api      # some other folder

.git, node_modules, .next, dist, .turbo, .venv, venv, __pycache__ und .DS_Store werden übersprungen. Die CLI gibt aus, wie viele Dateien sie gesendet hat, und danach wird genau wie bei einem Repository gebaut. Die App wird nach dem Ordner benannt, es sei denn, du gibst --name an.

Eine Katalog-Anwendung installieren

cloady deploy <applicationId> --type catalog

applicationId ist die Katalog-ID (wordpress, postgres, n8n, …) – dieselben IDs, die die Auswahl unter New Application im Dashboard zeigt. Workspace und Region werden genauso ermittelt wie bei einem Repository, und alle Flags von oben gelten. Nutze --value für die Einstellungen, nach denen die Anwendung fragt; alles, was du weglässt, bekommt seinen Standardwert oder ein generiertes Secret.

cloady deploy wordpress --type catalog -w acme --region eu1 --name blog
cloady deploy postgres  --type catalog -w acme --region eu1 --value POSTGRES_DB=app

Abfragen

cloady whoami                     # the authenticated user
cloady workspaces                 # your workspaces (alias: ws)
cloady regions                    # every region, with whether it's ready
cloady apps <workspace>           # apps in a workspace
cloady apps <workspace> --env production --region eu1

apps gibt eine Zeile pro App aus: ID, Status, Region, Umgebung, Name. Mit --json bekommst du die vollständigen Objekte – Endpunkte, Services, Ressourcenlimits, Quelle.

Lebenszyklus

Alle diese Befehle nehmen <workspace> <appId> entgegen, dazu --env (Standard production) und --region. Die Region kannst du weglassen, wenn die App-ID eindeutig ist – gibt es dieselbe ID in mehreren Regionen, bekommst du den Fehler region_required, der dich auffordert, sie anzugeben.

cloady start acme blog            # start a stopped app
cloady stop acme blog             # stop it; its data is kept
cloady redeploy acme blog         # rebuild the latest code and roll the containers
cloady restart acme blog          # alias for redeploy
cloady delete acme blog           # delete the app AND its data

delete wirkt sofort und ohne Rückfrage, und es löscht die Daten der App endgültig. Rückgängig machen lässt sich das nicht. Um den Namen oder die URL einer App zu ändern, benenne sie im Dashboard um – die Adresse folgt dem Namen, du musst also nie eine App löschen, um sie umzubenennen.

Einen Befehl in einem Container ausführen

cloady exec <workspace> <appId> --component <name> -- <command…>

Führt einen einmaligen Befehl in einem laufenden Container aus und zeigt seine Ausgabe an. Der Exit-Code des Befehls wird zum Exit-Code der CLI (124 bei einem Timeout), und per Pipe übergebenes stdin wird weitergeleitet.

cloady exec acme blog --component wordpress -- wp plugin list
cloady exec acme db --component postgres -- psql -U app -c 'select 1'
echo 'select count(*) from users;' | cloady exec acme db --component postgres -- psql -U app

Der Befehl läuft über /bin/sh -c – setz Pipes und Globs also in Anführungszeichen, wenn sie im Container ausgewertet werden sollen. Lange Ausgaben werden auf ihr Ende gekürzt, mit einem Hinweis auf stderr. Zwei Fehler gibt es nur bei exec: unknown_component bedeutet, dass die App keinen Service mit diesem Namen hat (sieh auf der Seite der App im Dashboard nach), und no_pod bedeutet, dass nichts läuft – starte die App zuerst.

Rezepte für Skripte

# wait until an app reports running
until cloady apps acme --json | jq -e '.[] | select(.slug=="blog" and .status=="running")' >/dev/null; do sleep 5; done

# redeploy from CI on every push to main
CLOADY_TOKEN=$CI_SECRET_TOKEN cloady redeploy acme api

# list every app across all workspaces
for ws in $(cloady ws --json | jq -r '.[].slug'); do cloady apps "$ws"; done

Für alles, was die CLI nicht abdeckt, greif direkt auf die REST-API zurück – gleiches Token, gleiche Basis-URL.