Referencia de la CLI

cloady despliega y gestiona tus aplicaciones desde una terminal. Llama a la misma API REST que usa el panel, así que todo lo que hagas con un script se comporta exactamente igual que hacerlo con clics en la interfaz.

Instalación

npm install -g cloady

Requiere Node 20+. Comprueba la instalación con:

cloady --version

Autenticación

cloady login sin argumentos abre tu navegador, muestra un código para que lo confirmes y guarda el token que recibe:

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

Añade --scope read, --scope deploy o --scope full (el valor predeterminado) para limitar lo que puede hacer ese token.

Si prefieres usar un token propio, créalo en el panel, en Account → API tokens (el valor, cldy_…, solo se muestra una vez), y pásalo como argumento:

cloady login cldy_…

En ambos casos, el token se guarda en ~/.config/cloady/config.json (modo 0600; respeta $XDG_CONFIG_HOME). cloady logout lo elimina.

Orden en el que se busca el token (gana la primera coincidencia):

1. La opción --token <token>
2. La variable de entorno CLOADY_TOKEN
3. El archivo de configuración guardado

Consejo para CI: sáltate login por completo y define CLOADY_TOKEN en el entorno del job.

Opciones globales

Todos los comandos aceptan:

Los errores se imprimen en stderr como error: <code>: <message> y terminan con un código de salida distinto de cero, así que las cadenas con && y los pasos de CI fallan como deben. Los que te encontrarás en la práctica:

Desplegar desde un repositorio

cloady deploy es el único comando para crear apps; --type indica de dónde viene el código (git, upload o catalog).

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

Qué pasa si no añades ninguna otra opción:

• Espacio de trabajo: si tienes exactamente uno, se usa ese. Si tienes varios, aparece un selector interactivo. Si no tienes ninguno, la CLI te guía para crear uno en ese mismo momento (nombre e id; un espacio de trabajo nuevo no cuesta nada).
• Región: aquella en la que ya se ejecutan la mayoría de tus apps o, si no, la primera región que esté lista. Elegir una región solo decide dónde se ejecuta esta app.
• Nombre: el nombre del repositorio.
• Entorno: production.

El build se hace en Cloady (se detecta tu stack, o se usa tu Dockerfile si el repo tiene uno), y la app responde en una URL como shop-k7q2v9ze-acme.cloady.io: el nombre de tu app, un código corto y el nombre de tu espacio de trabajo, con el HTTPS ya configurado. Las apps de preview y de desarrollo usan el mismo formato; el código corto hace que la URL de cada app sea única.

El comando termina en cuanto empieza el despliegue e imprime el id de la app, su estado y su URL; el build sigue en marcha después. Los repositorios privados funcionan una vez que el espacio de trabajo tiene GitHub conectado (Settings → Integrations).

Opciones, para todos los tipos de origen:

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

Cada app se ejecuta en una región y un entorno, y el nombre de una app es único dentro de un espacio de trabajo y un entorno.

Desplegar una carpeta local

Sin --type, cloady deploy comprime el directorio actual en un zip y lo sube; no hace falta ningún remoto de git:

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

Se omiten .git, node_modules, .next, dist, .turbo, .venv, venv, __pycache__ y .DS_Store. La CLI imprime cuántos archivos ha enviado y luego compila exactamente igual que con un repositorio. La app toma el nombre de la carpeta, salvo que pases --name.

Instalar una aplicación del catálogo

cloady deploy <applicationId> --type catalog

applicationId es el id del catálogo (wordpress, postgres, n8n, …), el mismo que muestra el selector New Application del panel. El espacio de trabajo y la región se resuelven igual que para un repositorio, y se aplican todas las opciones anteriores. Usa --value para los ajustes que pide la aplicación; lo que no indiques toma su valor predeterminado o un secreto generado.

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

Inspeccionar

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 imprime una línea por app: id, estado, región, entorno y nombre. Añade --json para obtener los objetos completos: endpoints, servicios, límites de recursos y origen.

Ciclo de vida

Todos estos comandos reciben <workspace> <appId>, además de --env (por defecto, production) y --region. Puedes omitir la región cuando el id de la app no es ambiguo; si el mismo id existe en varias regiones, recibirás un error region_required que te pide indicarla.

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 es inmediato y no pide confirmación, y elimina los datos de la app de forma permanente. No se puede deshacer. Para cambiar el nombre de una app o su URL, renómbrala en el panel: la dirección sigue al nombre, así que nunca elimines una app para cambiarle el nombre.

Ejecutar un comando en un contenedor

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

Ejecuta un comando puntual en un contenedor en ejecución e imprime su salida. El código de salida del comando pasa a ser el de la CLI (124 si se agota el tiempo), y si le pasas datos por una tubería, se reenvían a su stdin.

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

El comando se ejecuta a través de /bin/sh -c, así que pon entre comillas las tuberías y los globs si quieres que se evalúen dentro del contenedor. Si la salida es larga, se recorta y solo se muestra el final, con un aviso en stderr. Hay dos errores propios de exec: unknown_component significa que la app no tiene ningún servicio con ese nombre (revisa la página de la app en el panel), y no_pod significa que no hay nada en ejecución: inicia la app primero.

Recetas para scripts

# 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

Para lo que la CLI no cubre, recurre directamente a la API REST: el mismo token y la misma URL base.