npm package: @lerg96/gsheets-cli
Description: CLI tool for Google Sheets using Google Sheets API
Author: Luis Romero
Latest version: 1.0.0

# 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

```bash
npm install gsheets-cli -g
```

### Local

```bash
npm install
npm run build
```

## 🛠️ Configuración

### Opción 1: Configurar manualmente

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

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

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

```bash
# 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

```bash
gsheets config init
```

## 📚 Comandos

### Obtener datos

```bash
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

```bash
# 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)

```bash
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

```bash
# 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)

```bash
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

```bash
# 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

```bash
gsheets config list
```

#### Añadir perfil

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

#### Eliminar perfil

```bash
gsheets config remove-profile -n personal
```

#### Verificar credenciales

```bash
gsheets config verify
```

## 📊 Estructura de Salida

### JSON (default)

```json
[
  {
    "id": "123",
    "company": "Google",
    "email": "user@google.com"
  },
  {
    "id": "456",
    "company": "Microsoft",
    "email": "user@microsoft.com"
  }
]
```

### CSV

```csv
id,company,email
123,Google,user@google.com
456,Microsoft,user@microsoft.com
```

## 🔑 Credenciales

### Service Account Key (Recomendado)

1. Ve a [Google Cloud Console](https://console.cloud.google.com/)
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](https://console.cloud.google.com/)
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

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

### Filtrar datos

```bash
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

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

### Exportar a múltiples archivos

```bash
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

```bash
# 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

```bash
# 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