Clasp Master

CLASP Master

CLASP (Command Line Apps Script Projects) es el puente entre desarrollo local profesional y el ecosistema Google Workspace. Con clasp, Apps Script deja de ser un editor de browser y se convierte en un proyecto versionable, deployable desde CI/CD, y orquestable desde agentes.

1. INSTALACIÓN Y PREREQS

# Verificar Node.js (requiere >= v6, recomendado >= 18)
node -v && npm -v

# Instalar clasp globalmente
npm install -g @google/clasp

# Verificar instalación
clasp -v

# Habilitar Apps Script API (REQUERIDO antes de cualquier operación)
# https://script.google.com/home/usersettings → "Google Apps Script API" → ON

⚠️ CRÍTICO: La Google Apps Script API debe estar habilitada en la cuenta antes de clasp login.

2. AUTENTICACIÓN

clasp login                    # Abre browser para auth OAuth
clasp login --no-localhost     # Para entornos SSH/headless
clasp logout

# Multi-cuenta
clasp login --user personal
clasp login --user enterprise
clasp clone <scriptId> --user enterprise
clasp push --user enterprise

Credenciales en ~/.clasprc.json (default) y ~/.clasprc.<user>.json (named).

# OAuth client propio (enterprise)
clasp login --creds client_secret.json --user mykey

# Application Default Credentials (ADC / Service Account)
clasp push --adc
# Nota: SAs no pueden ser dueños de scripts — script debe estar compartido como Editor

3. GESTIÓN DE PROYECTOS

# Crear
clasp create --title "Mi Script" --type standalone
clasp create --title "Mi Script" --type sheets
clasp create --title "Mi Script" --type docs
clasp create --title "Mi Script" --type forms
clasp create --title "Mi Script" --type slides
clasp create --title "Mi Web App" --type webapp
clasp create --title "Mi Add-on" --type addon

# Clonar: Apps Script editor → Project Settings → Script ID
clasp clone <scriptId>
clasp clone <scriptId> --rootDir ./src

# Otros
clasp list       # Lista todos los proyectos
clasp open       # Abre en script.google.com
clasp open --webapp
clasp open --deploymentId <id>

4. SINCRONIZACIÓN

clasp pull                          # Descarga del proyecto
clasp pull --versionNumber 3        # Versión específica
clasp push                          # Sube archivos locales
clasp push --watch                  # Watch mode (dev loop)
clasp push -f                       # Force push

⚠️ REGLA DE ORO: No editar simultáneamente local Y script.google.com.

Estructura de directorios — clasp convierte automáticamente:

# Local:              → script.google.com:
src/utils/strings.gs → utils/strings.gs
src/Code.gs          → Code.gs

5. ARCHIVOS DE CONFIGURACIÓN

.clasp.json

{
  "scriptId": "1BxAbCdEfGhIjKlMnOpQrStUvWxYz_abc123",
  "rootDir": "./src",
  "projectId": "my-gcp-project-id",
  "fileExtension": "ts",
  "filePushOrder": ["src/init.ts", "src/Code.ts"]
}

.claspignore

node_modules/**
.git/**
**/*.test.ts
README.md
.env

.claspignore usa multimatch, diferente de .gitignore para directorios.

6. VERSIONES Y DEPLOYMENTS

clasp version "v1.0 - initial release"          # Crea versión
clasp versions                                   # Lista versiones

clasp deploy                                     # Deploy HEAD
clasp deploy --versionNumber 2 --description "hotfix"
clasp deployments                                # Lista deployments
clasp undeploy <deploymentId>
clasp undeploy --all
clasp redeploy <deploymentId> <version> "desc"

Workflow prod:

clasp push
clasp version "v2.1 - new feature X"
clasp deploy --versionNumber 3 --description "Production v2.1"

7. EJECUCIÓN REMOTA (clasp run)

# Setup: asociar GCP Project + OAuth Client ID Desktop
clasp login --creds client_secret.json --user runkey --use-project-scopes
# Agregar projectId al .clasp.json

clasp run                        # Prompt interactivo
clasp run helloWorld             # Función específica
clasp run myFunction -- arg1

8. LOGS

clasp logs                 # StackDriver recientes (solo console.log, NO Logger.log)
clasp logs --watch         # Streaming tiempo real
clasp logs --simplified

9. TYPESCRIPT

npm install -D @types/google-apps-script typescript

// .clasp.json
{ "scriptId": "...", "rootDir": "./src", "fileExtension": "ts" }

// tsconfig.json
{ "compilerOptions": { "target": "ES2019", "lib": ["ES2019"], "strict": false } }

10. GIT INTEGRATION

# pre-push hook
#!/bin/bash
$(which clasp) push

chmod +x .git/hooks/pre-push

# Multi-env con clasp-env
npm install -D clasp-env
# package.json:
# "push:dev":  "clasp-env --folder src --scriptId DEV_ID && clasp push -w"
# "push:prod": "clasp-env --folder src --scriptId PROD_ID && clasp push"

Agregar .clasp.json a .gitignore en setups multi-env.

11. MCP MODE (integración con agentes)

# Configurar como MCP server (Gemini CLI, Claude Code):
clasp mcp --transport stdio

# mcp_settings.json:
{
  "mcpServers": {
    "clasp": { "command": "clasp", "args": ["mcp", "--transport", "stdio"] }
  }
}

Prerequisito: clasp login previo. Project dir se especifica en cada tool call.

12. WORKFLOWS COMUNES

# Script nuevo desde cero
mkdir mi-automation && cd mi-automation
clasp login
clasp create --title "Mi Automation" --type sheets
clasp pull
# ... editar localmente ...
clasp push
clasp version "v1.0"
clasp deploy --versionNumber 1 --description "Producción"

# Tomar control de script existente
mkdir proyecto && cd proyecto
clasp clone <scriptId>
git init && git add . && git commit -m "init: clonar proyecto existente"

# CI/CD (GitHub Actions):
# npm install -g @google/clasp
# echo $CLASP_RC > ~/.clasprc.json
# clasp push && clasp version "Build $SHA" && clasp deploy ...

13. TROUBLESHOOTING

REFERENCIA RÁPIDA

clasp login / logout / login --no-localhost / login --user <n>
clasp create --title "X" --type [standalone|sheets|docs|forms|slides|webapp|addon]
clasp clone <scriptId> | clasp list | clasp open [--webapp]
clasp pull [--versionNumber N] | clasp push [-f] [--watch]
clasp version "desc" | clasp versions
clasp deploy [--versionNumber N] [--description "desc"]
clasp deployments | clasp undeploy <id> | clasp redeploy <id> <v> "desc"
clasp run [functionName] | clasp logs [--watch]
clasp status | clasp mcp --transport stdio

NOTA AUTOLIFE / CHEF COGNITIVO

• clasp + MCP mode = Apps Script ejecutable desde Claude/Gemini directamente
• clasp + GitHub Actions = CI/CD completo para GAS
• clasp run = invocar funciones GAS desde scripts locales (bridge Python/Node ↔ GAS)
• Enterprise logging: console.log + clasp logs --watch + StackDriver = traza completa

Ver references/appsscript-manifest.md para detalles del manifest y OAuth scopes.