@iclouds-mx/cli

CLI oficial de iClouds para autenticarte, listar tus proyectos y apps, y desplegar desde la terminal. Reutiliza el puerto, los nodos, las variables de entorno y la configuración de build que ya tiene la app en el panel.

Requisitos

• Node.js 20 o superior.
• Una cuenta de iClouds (panel) con al menos un proyecto.
• API por defecto: https://api.iclouds.mx.

Instalación

npm i -g @iclouds-mx/cli
iclouds --version

Sin instalarlo:

npx @iclouds-mx/cli --help

Autenticación

iclouds login

Pide email y contraseña del panel, los canjea por un token de API (prefijo icl_…, scopes deploy:read y deploy:write) y lo guarda con permisos 600 en:

$XDG_CONFIG_HOME/iclouds/config.json   # por defecto ~/.config/iclouds/config.json

Para CI puedes omitir el login y pasar un token por variables de entorno:

export ICLOUDS_TOKEN=icl_...
export ICLOUDS_API_URL=https://api.iclouds.mx

También se puede iniciar sesión con un token existente:

iclouds login --token icl_...

En CI, para no dejar la contraseña en el historial:

echo "$ICLOUDS_PASSWORD" | iclouds login --email [email protected] --password-stdin

iclouds whoami     # muestra la sesión actual
iclouds logout     # elimina el token guardado

Comandos

| Comando | Descripción | |---|---| | iclouds login | Inicia sesión y guarda un token de API | | iclouds whoami | Muestra la sesión actual | | iclouds logout | Elimina el token guardado | | iclouds projects list | Lista tus proyectos | | iclouds apps list [--project <id>] | Lista tus apps | | iclouds init [path] | Crea iclouds.json en el repo | | iclouds deploy [path] | Empaqueta y despliega | | iclouds logs [appId] [--follow] | Muestra/sigue los eventos del deploy |

Selección interactiva

iclouds deploy (sin --app) y iclouds init preguntan el proyecto y la app cuando estás en una terminal interactiva. --app y --project aceptan ID, nombre o dominio:

iclouds deploy --app iwebsapp.com
iclouds apps list --project iws

En CI (sin TTY) debes indicar --app explícitamente.

Flags de deploy

| Flag | Descripción | |---|---| | --zip <file> | Usa un ZIP existente en vez de empaquetar el repo | | --app <id\|nombre> | App destino (ID, nombre o dominio) | | --project <id\|nombre> | Proyecto destino | | --port <number> | Puerto a exponer | | --env K=V | Variable de entorno (repetible) | | --node <version> | Versión de Node | | --build <command> | Comando de build | | --start <command> | Comando de inicio | | --package-manager <pm> | npm | yarn | pnpm | bun | | --type <auto\|static\|node> | Tipo de deploy | | --health-path <path> | Ruta de health check | | --servers ip1,ip2 | Nodos destino (IPs separadas por coma) | | --no-wait | Inicia el deploy y sale sin esperar eventos | | --timeout <seconds> | Segundos de espera de los eventos | | --json | Salida JSON (para CI) |

Los flags sobrescriben iclouds.json y la configuración guardada de la app. Si no se especifican, se reutilizan el puerto, nodos, env, versión de Node y comandos de build/start que ya tiene la app (no se borran variables).

Ejemplos

iclouds deploy
iclouds deploy --app mi-app.com
iclouds deploy ./mi-app --env NODE_ENV=production --env API_URL=https://api.mi-app.com
iclouds deploy --zip ./build.zip --servers 100.64.0.1,100.64.0.2
iclouds deploy --no-wait --json
iclouds logs mi-app.com --follow
iclouds projects list

Durante el deploy se muestra el progreso por etapas: empaquetado, subida (S3 si ≤ 90 MB, multipart si no) y eventos del servidor en vivo. Si la conexión se corta, el CLI confirma el resultado consultando los eventos.

iclouds.json

iclouds init crea un iclouds.json en el repo para no repetir flags:

{
  "projectId": "60d21b4667d0d8992e610c86",
  "appId": "60d21b4667d0d8992e610c85",
  "nodeVersion": "22",
  "packageManager": "npm",
  "buildCommand": "npm run build",
  "startCommand": "npm start",
  "deployType": "auto",
  "env": {
    "NODE_ENV": "production"
  }
}

Opcionalmente admite port, servers y healthPath. Para apps existentes, init precarga estos valores desde la propia app.

Códigos de salida

| Código | Significado | |---|---| | 0 | Éxito | | 1 | Error genérico | | 2 | Error de autenticación (401/403, token ausente o sin scope) | | 3 | El deploy falló | | 4 | Error de red o timeout |

Empaquetado del ZIP

El ZIP respeta .gitignore y .icloudsignore, e excluye por defecto node_modules, .git, dist, .next, build, coverage, .iclouds, iclouds.json, logs y secretos (.env, .env.local, .env.*.local, .npmrc, *.pem, *.key, *.p12, *.pfx). Usa --zip para desplegar un ZIP propio.

Seguridad

• La API debe usar HTTPS; HTTP solo se acepta en localhost o con ICLOUDS_ALLOW_INSECURE=1 (evita enviar el token en claro).
• La config se guarda 0600 (directorio 0700), se corrigen permisos laxos al leer y se rechaza escribirla a través de un symlink.
• No se suben credenciales en el ZIP; las claves de entorno peligrosas (__proto__, constructor, prototype) se rechazan.
• Las peticiones usan redirect: "error"; la subida a S3 tiene timeout propio.
• --token/--password en la línea de comandos quedan en el historial (el CLI avisa); para CI usa ICLOUDS_TOKEN o --password-stdin.

Notas

• Deploys largos: el POST /apps/deploy del backend es síncrono y puede tardar minutos; el CLI mantiene la petición abierta y usa un fallback por eventos si el proxy corta la conexión.
• Scopes: un token sin deploy:write no puede desplegar (403). Los tokens se revocan desde el panel o con DELETE /platform/tokens/:id.
• Paquetes de sistema: un token de API actúa con rol user, así que systemPackages se define desde el panel; el CLI conserva el env y la config de build existentes.
• Los ZIP de más de ~90 MB se suben por multipart directo en lugar de S3 (límite de Cloudflare).

Documentación

| Documento | Contenido | |---|---| | docs/ARCHITECTURE.md | Capas, archivos, flujo de datos y exit codes | | docs/COMMANDS.md | Referencia de comandos y flags | | docs/DEPLOY.md | Flujo de deploy (empaquetado, subida, timeout, eventos) | | docs/CONFIG.md | Config global, iclouds.json y variables de entorno | | docs/SECURITY.md | Auditoría de seguridad y mitigaciones | | docs/DEVELOPMENT.md | Setup, tests, convenciones y publicación | | AGENTS.md | Guía para agentes (invariantes y estructura) |

Desarrollo

npm install
npm run dev         # tsx src/cli.ts
npm test            # jest
npm run typecheck   # tsc --noEmit
npm run lint
npm run build       # tsup → dist/cli.js

Publicación

npm publish --access public

El paquete se publica en el scope @iclouds-mx (requiere token npm con Bypass 2FA).