gsheets-cli

CLI tool for Google Sheets using the Google Sheets API. Allows you to read, append, and update data in Google Sheets with flexible output options.

🚀 Características

• ✅ Lectura de datos: Obtén datos de cualquier hoja de cálculo de Google
• ✅ Múltiples formatos: Salida en JSON (pretty-print o minificado) o CSV
• ✅ Personalización: Define columnas personalizadas y salta filas
• ✅ Gestión de credenciales: Soporte para Service Account y API Key
• ✅ Escritura de datos: Comandos append y update para modificar hojas
• ✅ Tipado TypeScript: Código completamente tipado
• ✅ Pruebas unitarias: Suite de tests con Jest
• ✅ Múltiples perfiles: Gestiona diferentes configuraciones de credenciales

📦 Instalación

Global

npm install gsheets-cli -g

Local

npm install
npm run build

🛠️ Configuración

Opción 1: Configurar manualmente

Crea el archivo ~/.config/gsheets/config.json:

{
  "profiles": {
    "personal": {
      "type": "service_account",
      "serviceAccountKey": "{}"
    }
  },
  "defaultProfile": "personal"
}

Opción 2: Usar el comando config add-profile

# Añadir un perfil con Service Account
gsheets config add-profile -n personal --type service_account --key "<your-service-account-key-json>"

# Añadir un perfil con API Key
gsheets config add-profile -n work --type api_key --key "<your-api-key>"

Opción 3: Configurar interactivamente

gsheets config init

📚 Comandos

Obtener datos

gsheets get [opciones]

Opciones

| Opción | Descripción | | --------------------------- | -------------------------------------------------------------- | | -s, --spreadsheet-id <id> | ID de la hoja de cálculo (requisito) | | -r, --range <range> | Rango a obtener (ej: "A1:Z100" o "Sheet1!A1:Z100") (requisito) | | -o, --output <format> | Formato de salida: json o csv (default: json) | | --header <columns> | Columnas personalizadas (separadas por coma) | | --skip-header | Saltar la primera fila | | --minified | JSON minificado (default: pretty-print) | | -p, --profile <name> | Perfil a usar |

Ejemplos

# Obtener todo el rango A1:Z100 como JSON
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:Z100"

# Obtener solo columnas A y B
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100"

# Personalizar headers
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" --header "id,name,email"

# Saltar la primera fila
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A2:B100" --skip-header

# Output CSV
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" -o csv

# JSON minificado
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" --minified

# Usar un perfil específico
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" --profile work

# Canalizar a un archivo
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" > data.json

Añadir datos (Append)

gsheets append [opciones]

Opciones

| Opción | Descripción | | --------------------------- | ----------------------------------------------------- | | -s, --spreadsheet-id <id> | ID de la hoja de cálculo (requisito) | | -r, --range <range> | Rango donde añadir datos (requisito) | | -i, --input <file> | Archivo de entrada (JSON o CSV) (requisito) | | -o, --output <format> | Formato de entrada: json o csv (default: auto-detect) | | -p, --profile <name> | Perfil a usar |

Ejemplos

# Añadir datos desde JSON
gsheets append -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A2:Z100" -i data.json

# Añadir datos desde CSV
gsheets append -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A2:Z100" -i data.csv -o csv

# Añadir datos con headers personalizados
gsheets append -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A2:Z100" -i items.json

Actualizar datos (Update)

gsheets update [opciones]

Opciones

| Opción | Descripción | | --------------------------- | ----------------------------------------------------- | | -s, --spreadsheet-id <id> | ID de la hoja de cálculo (requisito) | | -r, --range <range> | Rango a actualizar (requisito) | | -i, --input <file> | Archivo de entrada (JSON o CSV) (requisito) | | -o, --output <format> | Formato de entrada: json o csv (default: auto-detect) | | -p, --profile <name> | Perfil a usar |

Ejemplos

# Actualizar valores en un rango específico
gsheets update -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B10" -i updates.json

# Actualizar desde CSV
gsheets update -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B10" -i updates.csv -o csv

Configurar credenciales

Listar perfiles

gsheets config list

Añadir perfil

gsheets config add-profile -n personal --type service_account --key "<key-json>"

Eliminar perfil

gsheets config remove-profile -n personal

Verificar credenciales

gsheets config verify

📊 Estructura de Salida

JSON (default)

[
  {
    "id": "123",
    "company": "Google",
    "email": "[email protected]"
  },
  {
    "id": "456",
    "company": "Microsoft",
    "email": "[email protected]"
  }
]

CSV

id,company,email
123,Google,[email protected]
456,Microsoft,[email protected]

🔑 Credenciales

Service Account Key (Recomendado)

1. Ve a Google Cloud Console
2. Crea un nuevo proyecto
3. Habilita la API de Google Sheets
4. Crea un Service Account
5. Descarga la clave JSON
6. Usa la clave en la configuración

API Key

1. Ve a Google Cloud Console
2. Crea un nuevo proyecto
3. Ve a API & Services > Credentials
4. Crea una API Key
5. Usa la key en la configuración

⚠️ Limitaciones

• API Key: Tiene limitaciones de uso y no puede acceder a todos los recursos
• Service Account: Requiere permisos adecuados en la hoja de cálculo
• Rango: Debe ser un rango válido (ej: A1:Z100)

💡 Ejemplos de Uso

Pipeline con jq

gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" | jq '.[] | {name: .company, id: .id}'

Filtrar datos

gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" --header "id,name" | \
  grep -o '{[^}]*}' | \
  while read line; do echo "$line" | jq '.name as $n | select($n | contains("Google"))'; done

Guardar como CSV

gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" -o csv > data.csv

Exportar a múltiples archivos

for sheet in "Sales" "Inventory" "Customers"; do
  gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "${sheet}!A1:Z100" --header "id,name,value" > "${sheet}.csv"
done

Procesamiento en batch

# Descargar, transformar y subir datos
gsheets get -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A1:B100" -o csv | \
  sed 's/,/;/g' > processed.csv

gsheets append -s "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" -r "A2:Z100" -i processed.csv -o csv

🧪 Pruebas Unitarias

# Ejecutar todas las pruebas
npm test

# Ejecutar con aumento de memoria (requerido en algunos sistemas)
bash scripts/run-tests.sh

📁 Estructura del Proyecto

gsheets-cli/
├── src/
│   ├── cli.ts              # CLI principal con Commander
│   ├── config/             # Gestión de credenciales
│   │   └── index.ts
│   ├── services/           # Wrapper de la API de Google Sheets
│   │   └── SheetsService.ts
│   └── utils/              # Utilidades de transformación
│       └── transform.ts
├── __tests__/
│   ├── cli/
│   ├── config/
│   ├── services/
│   └── utils/
├── dist/                   # Build compilado
├── scripts/
│   └── run-tests.sh        # Script para ejecutar tests
├── package.json
├── tsconfig.json
├── jest.config.js
├── .eslintrc.json
├── .prettierrc.json
└── README.md

📜 Licencia

MIT

Made with ❤️ for developers who love Google Sheets