Home

spa-cli — Guía rápida

Esta página documenta los comandos reales del proyecto spa-cli (CLI para proyectos serverless en Python).

Ejecutables instalados: spa y spa-cli (ambos apuntan al mismo spa_cli.cli:app).

spa
├─ project
│  ├─ init         # Inicializar proyecto (interactive)
│  ├─ install      # Instalar capas locales (layers)
│  ├─ run-api      # Iniciar servidor local para la API
│  ├─ build        # Construir proyecto para deployment (--api-build-mode serverless|container)
│  └─ docker-init  # Generar Dockerfile, docker-compose.yml, entrypoint.sh, .dockerignore
├─ endpoint
│  └─ add          # Agregar endpoint HTTP y lambda asociada (--method --path --endpoint-name)
├─ lambda
│  └─ add          # Crear lambda independiente (--lambda-name)
└─ authorizer
   └─ add          # Generar Lambda Authorizer (corre como middleware en modo container)

Versión

Muestra la versión del CLI:

spa --version
spa-cli --version

Comandos principales

El CLI tiene cuatro grupos de subcomandos principales: project, endpoint, lambda y authorizer.

1) Comandos del proyecto (spa project)

• spa project init

  • Genera un nuevo proyecto a partir del template.
  • Opciones: pattern_version (por defecto latest).
  • El comando interactivo pedirá: nombre del proyecto, descripción, autor, email, motor de BD, región AWS y nombre del secreto para credenciales.

  Ejemplo:

  spa project init

• spa project install

  • Instala las capas (layers) locales del proyecto y sus dependencias.

  Ejemplo:

  spa project install

• spa project run-api

  • Inicia el servidor local para desarrollo y pruebas de la API (simula Lambdas localmente).

  Ejemplo:

  spa project run-api

• spa project build

  • Construye el proyecto para deployment: empaqueta layers, lambdas, copia infra y genera openapi.json en el build.
  • Opción --api-build-mode {serverless|container}. Si no se pasa, lee api_build_mode de [spa.project.definition] en spa_project.toml. Si tampoco está definido, falla.
  • Flag --yes / -y: omite confirmaciones interactivas (útil en CI/CD).
  • En modo container: omite lambdas con endpoint.yaml (ya expuestas por FastAPI), detecta y comenta bloques de ApiGateway en infra/__main__.py, y genera build/src/api_local/{main_server.py, router.py, openapi.json, auth_bridge.py, auth_bridge.config.json}.

  Ejemplo:

  spa project build                               # lee api_build_mode del toml
  spa project build --api-build-mode container    # fuerza modo container
  spa project build --api-build-mode container -y # container sin prompts

• spa project docker-init

  • Genera Dockerfile, docker-compose.yml, entrypoint.sh y .dockerignore en la raíz del proyecto a partir de templates internos del paquete.
  • Flag --force sobreescribe archivos existentes.

  Ejemplo:

  spa project docker-init
  spa project docker-init --force

2) Comandos de endpoints (spa endpoint)

• spa endpoint add

  • Agrega un nuevo endpoint HTTP y su carpeta de Lambda asociada.
  • Opciones (requeridas):
    • --method : Método HTTP (GET, POST, PUT, PATCH, DELETE)
    • --path : Ruta del endpoint (por ejemplo /usuarios)
    • --endpoint-name : Nombre de la función lambda (sin espacios ni guiones)

  Ejemplo:

  spa endpoint add --method POST --path /usuarios --endpoint-name crear_usuario

3) Comandos de Lambda (spa lambda)

• spa lambda add

  • Crea una nueva función Lambda (sin endpoint HTTP asociado).
  • Opciones:
    • --lambda-name : Nombre de la función lambda (sin espacios ni guiones)

  Ejemplo:

  spa lambda add --lambda-name procesar_facturas

4) Comandos de Authorizer (spa authorizer)

• spa authorizer add <name>

  • Genera el stub de un Lambda Authorizer en src/authorizers/<name>/handler.py (template basado en validación Cognito + IAM policy).
  • Registra [spa.api.lambda-authorizers.<name>] en spa_project.toml con module = "src.authorizers.<name>.handler".
  • El handler corre en dos contextos sin cambios: como Lambda real (deploy serverless con API Gateway) y como middleware FastAPI dentro del container (auth_bridge.py lo invoca cuando un request hace match con una ruta protegida en el OpenAPI).
  • Opciones:
    • --role-name : Nombre del IAM role (default <name>-authorizer-role).
    • --lambda-name : Nombre de la función Lambda (default <name>-authorizer).

  Ejemplo:

  spa authorizer add principal
  spa authorizer add admin --role-name admin-auth-role --lambda-name admin-authorizer

  Ver detalle en lambda-authorizers.md y authorizer.md.

Comandos no habilitados

El grupo model existe en el código base pero no está activado en el CLI principal (comentado en spa_cli/cli.py). Por eso las instrucciones de spa model no están disponibles en la versión actual.

Configuración del proyecto

El archivo de configuración se llama spa_project.toml. Si spa project init no encuentra uno, el comando load_config crea un spa_project.toml con valores por defecto en el directorio del proyecto.

Ejemplo de flujo de trabajo típico

# 1. Inicializar proyecto
spa project init

# 2. Instalar capas locales
spa project install

# 3. Agregar endpoints
spa endpoint add --method GET --path /usuarios --endpoint-name listar_usuarios
spa endpoint add --method POST --path /usuarios --endpoint-name crear_usuario

# 4. Agregar funciones lambda adicionales
spa lambda add --lambda-name procesar_imagenes

# 5. (Opcional) Configurar authorizers
spa authorizer add principal

# 6. Probar localmente
spa project run-api

# 7. Construir para deployment
spa project build                               # serverless (del toml) o fuerza con --api-build-mode
spa project build --api-build-mode container    # listo para Docker

Notas y recomendaciones

• Los nombres de lambda/endpoint no deben contener espacios ni guiones; el CLI los sustituye por guiones bajos si los detecta.
• Si necesitas ver ayuda detallada de cualquier comando: spa <grupo> --help o spa <grupo> <comando> --help.

---

Documento generado para coincidir con los subcomandos reales definidos en el código fuente del proyecto (vistas en spa_cli/cli.py y en spa_cli/src/*).