check
Verify configuration and connectivity.
```bash
python scripts/google-sheets.py check
```
This validates:
- Python dependencies are installed
- Authentication is configured
- Can connect to Google Sheets API
- Creates a test spreadsheet to verify write access
auth setup
Store OAuth 2.0 client credentials for custom OAuth flow.
```bash
python scripts/google-sheets.py auth setup \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET
```
Credentials are saved to ~/.config/agent-skills/google-sheets.yaml.
Options:
--client-id - OAuth 2.0 client ID (required)--client-secret - OAuth 2.0 client secret (required)
spreadsheets create
Create a new Google Sheets spreadsheet.
```bash
python scripts/google-sheets.py spreadsheets create --title "My Spreadsheet"
```
Options:
--title - Spreadsheet title (required)--sheets - Comma-separated sheet names (optional)--json - Output as JSON
Example:
```bash
# Create with default Sheet1
python scripts/google-sheets.py spreadsheets create --title "Sales Data"
# Create with custom sheets
python scripts/google-sheets.py spreadsheets create \
--title "Q1 Report" \
--sheets "Summary,January,February,March"
# Output:
# β Spreadsheet created successfully
# Title: Q1 Report
# Spreadsheet ID: 1abc...xyz
# Sheets: 4 (Summary, January, February, March)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit
```
spreadsheets get
Get spreadsheet metadata and structure.
```bash
python scripts/google-sheets.py spreadsheets get SPREADSHEET_ID
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--json - Output full spreadsheet structure as JSON
Example:
```bash
python scripts/google-sheets.py spreadsheets get 1abc...xyz
# Output:
# Title: Sales Data
# Spreadsheet ID: 1abc...xyz
# Sheets: 2 (Sheet1, Summary)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit
```
values read
Read cell values from a range.
```bash
python scripts/google-sheets.py values read SPREADSHEET_ID --range "Sheet1!A1:D5"
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--range - Range in A1 notation (required, e.g., "Sheet1!A1:D5")--format - Value format: FORMATTED_VALUE (default), UNFORMATTED_VALUE, or FORMULA--json - Output as JSON
Example:
```bash
# Read a range
python scripts/google-sheets.py values read 1abc...xyz --range "Sheet1!A1:C3"
# Output (formatted as table):
# Name | Age | City
# Alice | 30 | NYC
# Bob | 25 | LA
# Read formulas
python scripts/google-sheets.py values read 1abc...xyz \
--range "Sheet1!D1:D10" \
--format FORMULA
```
See [references/range-notation.md](references/range-notation.md) for A1 notation details.
values write
Write values to a range.
```bash
python scripts/google-sheets.py values write SPREADSHEET_ID \
--range "Sheet1!A1" \
--values '[[\"Name\",\"Age\"],[\"Alice\",30]]'
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--range - Starting range in A1 notation (required)--values - Values as JSON 2D array (required)--json - Output API response as JSON
Example:
```bash
# Write data starting at A1
python scripts/google-sheets.py values write 1abc...xyz \
--range "Sheet1!A1" \
--values '[[\"Product\",\"Price\",\"Quantity\"],[\"Widget\",9.99,100]]'
# Write a single row
python scripts/google-sheets.py values write 1abc...xyz \
--range "Sheet1!A5" \
--values '[[\"Total\",999,50]]'
# Output:
# β Values written successfully
# Updated cells: 6
# Updated range: Sheet1!A1:C2
```
Note: Values are entered as the user would type them. Formulas start with =.
values append
Append rows to the end of a sheet.
```bash
python scripts/google-sheets.py values append SPREADSHEET_ID \
--range "Sheet1" \
--values '[[\"New\",\"Row\",\"Data\"]]'
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--range - Sheet name or range (required)--values - Values as JSON 2D array (required)--json - Output API response as JSON
Example:
```bash
# Append a single row
python scripts/google-sheets.py values append 1abc...xyz \
--range "Sheet1" \
--values '[[\"Charlie\",35,\"Chicago\"]]'
# Append multiple rows
python scripts/google-sheets.py values append 1abc...xyz \
--range "Sheet1" \
--values '[[\"David\",28,\"Boston\"],[\"Eve\",32,\"Seattle\"]]'
# Output:
# β Values appended successfully
# Updated cells: 3
# Updated range: Sheet1!A4:C4
```
values clear
Clear values in a range.
```bash
python scripts/google-sheets.py values clear SPREADSHEET_ID --range "Sheet1!A1:D10"
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--range - Range in A1 notation (required)--json - Output API response as JSON
Example:
```bash
# Clear a range
python scripts/google-sheets.py values clear 1abc...xyz --range "Sheet1!A1:Z100"
# Output:
# β Values cleared successfully
# Cleared range: Sheet1!A1:Z100
```
Warning: This only clears values, not formatting or formulas in protected cells.
sheets create
Add a new sheet to a spreadsheet.
```bash
python scripts/google-sheets.py sheets create SPREADSHEET_ID --title "New Sheet"
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--title - Sheet title (required)--json - Output API response as JSON
Example:
```bash
python scripts/google-sheets.py sheets create 1abc...xyz --title "Q2 Data"
# Output:
# β Sheet created successfully
# Title: Q2 Data
# Sheet ID: 123456789
```
sheets delete
Delete a sheet from a spreadsheet.
```bash
python scripts/google-sheets.py sheets delete SPREADSHEET_ID --sheet-id 123456789
```
Arguments:
spreadsheet_id - The Google Sheets spreadsheet ID
Options:
--sheet-id - Sheet ID (required, not the title!)--json - Output API response as JSON
Example:
```bash
# Get sheet IDs first
python scripts/google-sheets.py spreadsheets get 1abc...xyz --json | jq '.sheets[].properties | {title, sheetId}'
# Delete a sheet
python scripts/google-sheets.py sheets delete 1abc...xyz --sheet-id 123456789
# Output:
# β Sheet deleted successfully
```
Warning: Cannot delete the last remaining sheet in a spreadsheet.
|