Google Sheets
Purpose
Manage Google Sheets through hatch_gws_cli; the vendored Google Workspace CLI is the only implementation path.
Tooling
Use exec to run:
hatch_gws_cli sheets <resource> <method> [flags]
Connection management
hatch_gws_cli sheets status
hatch_gws_cli sheets disconnect
Sheets operations
Core patterns:
hatch_gws_cli sheets status
hatch_gws_cli sheets disconnect
hatch_gws_cli schema sheets.spreadsheets.get
hatch_gws_cli schema sheets.spreadsheets.create
hatch_gws_cli schema sheets.spreadsheets.values.get
hatch_gws_cli schema sheets.spreadsheets.values.append
hatch_gws_cli schema sheets.spreadsheets.batchUpdate
Common raw API calls:
hatch_gws_cli sheets spreadsheets get --params '{"spreadsheetId":"<spreadsheet_id>"}'
hatch_gws_cli sheets spreadsheets create --json '{"properties":{"title":"My Spreadsheet"}}'
hatch_gws_cli sheets spreadsheets values get --params '{"spreadsheetId":"<spreadsheet_id>","range":"Sheet1!A1:D10"}'
hatch_gws_cli sheets spreadsheets values append --params '{"spreadsheetId":"<spreadsheet_id>","range":"Sheet1!A:D","valueInputOption":"USER_ENTERED"}' --json '{"values":[["a","b"],["c","d"]]}'
hatch_gws_cli sheets spreadsheets batchUpdate --params '{"spreadsheetId":"<spreadsheet_id>"}' --json '{"requests":[{"addSheet":{"properties":{"title":"Q2"}}}]}'
Vendored helpers are also available:
hatch_gws_cli sheets +read ...
hatch_gws_cli sheets +append ...
JSON output contract:
status: parse status, connect_url, and disconnect_url
disconnect: parse ok, action, status, and disconnect_url
Formatting spreadsheet content
Write and format the spreadsheet through the Sheets API. Do not upload a file over it.
- Write the values with
spreadsheets.create, values.update, or values.append. Set valueInputOption to USER_ENTERED so Sheets parses dates, currency, and formulas.
- Set the styling in one
spreadsheets.batchUpdate call. repeatCell with userEnteredFormat sets the header style and the number formats. updateSheetProperties freezes the header row. updateDimensionProperties sets column widths. A new spreadsheet can carry these formats in the spreadsheets.create body instead.
- Read the result back before you call it ready. A successful write proves the API accepted the request, not that the sheet reads correctly.
spreadsheets.get returns no cell data by default, so pass a field mask: hatch_gws_cli sheets spreadsheets get --params '{"spreadsheetId":"<spreadsheet_id>","ranges":"<tab>!A1:F10","fields":"sheets(properties(title,gridProperties(frozenRowCount)),data(rowData(values(formattedValue,effectiveFormat(backgroundColor,numberFormat,textFormat)))))"}'
- Never publish a
.xlsx file over a spreadsheet with drive files update. Google replaces the full contents of the file, so that upload discards every other tab and every edit the user made. To change one part of a spreadsheet, use values.update or spreadsheets.batchUpdate. To give the user a workbook to download, build a spreadsheet artifact and attach the file.
Auth
Authentication is handled by the wrapper's status and disconnect subcommands. Do not hand-write credential files or run raw gws auth ....
First-use setup flow
- Run
hatch_gws_cli sheets status.
- If
status is unavailable, tell the user that Google Sheets is not available on this device. Do not offer alternative integration approaches or ask the user for credentials.
- If
status is not_connected and connect_url is present, replace <connect_url> with the returned URL and share exactly this Markdown link: [Connect Google Sheets](<connect_url>); do not paste the raw URL separately. Wait for the user to reconnect.
- Once
status is connected, proceed with Sheets operations.
Operating Rules
- Use
schema before unfamiliar Sheets methods so --params and --json match the current vendored CLI contract.
- Use A1 notation for ranges unless the user explicitly wants a different API path.
- Creating a spreadsheet, clearing cells, and editing a spreadsheet owned only by the user may proceed from a clear request. Confirm before editing a shared spreadsheet because its contents can be exposed to or changed for other people.
- Treat spreadsheet IDs and sheet IDs as opaque strings and only use IDs returned by prior commands or explicit user input.
- Run
hatch_gws_cli sheets disconnect. After running it, when disconnect_url is present, replace <disconnect_url> with the returned URL and share exactly this Markdown link: [Disconnect Google Sheets](<disconnect_url>); do not paste the raw URL separately.
- Prefer
spreadsheets.get or sheets +read before writing when you need to inspect current sheet structure or cell contents. To write or style a sheet, follow "Formatting spreadsheet content" above.
- After a read or write action, confirm the user-visible result only. Do not surface raw API identifiers (spreadsheet and sheet IDs) or other internal response fields (page tokens/cursors, raw JSON) in text shown to the user unless the user asks for them or you need them to troubleshoot a failure; keep using them internally to chain follow-up commands.
1---2name: google-sheets3description: "Read, write, and manage the user's Google Sheets."4icon: "google_sheets"5metadata:6 source: https://skillmd.com/skills/win4r/google-sheets7 includeInPrompt: false8---910# Google Sheets1112## Purpose13Manage Google Sheets through `hatch_gws_cli`; the vendored Google Workspace CLI is the only implementation path.1415## Tooling16Use `exec` to run:1718```sh19hatch_gws_cli sheets <resource> <method> [flags]20```2122### Connection management2324```sh25hatch_gws_cli sheets status26hatch_gws_cli sheets disconnect27```2829### Sheets operations3031Core patterns:32- `hatch_gws_cli sheets status`33- `hatch_gws_cli sheets disconnect`34- `hatch_gws_cli schema sheets.spreadsheets.get`35- `hatch_gws_cli schema sheets.spreadsheets.create`36- `hatch_gws_cli schema sheets.spreadsheets.values.get`37- `hatch_gws_cli schema sheets.spreadsheets.values.append`38- `hatch_gws_cli schema sheets.spreadsheets.batchUpdate`3940Common raw API calls:41- `hatch_gws_cli sheets spreadsheets get --params '{"spreadsheetId":"<spreadsheet_id>"}'`42- `hatch_gws_cli sheets spreadsheets create --json '{"properties":{"title":"My Spreadsheet"}}'`43- `hatch_gws_cli sheets spreadsheets values get --params '{"spreadsheetId":"<spreadsheet_id>","range":"Sheet1!A1:D10"}'`44- `hatch_gws_cli sheets spreadsheets values append --params '{"spreadsheetId":"<spreadsheet_id>","range":"Sheet1!A:D","valueInputOption":"USER_ENTERED"}' --json '{"values":[["a","b"],["c","d"]]}'`45- `hatch_gws_cli sheets spreadsheets batchUpdate --params '{"spreadsheetId":"<spreadsheet_id>"}' --json '{"requests":[{"addSheet":{"properties":{"title":"Q2"}}}]}'`4647Vendored helpers are also available:48- `hatch_gws_cli sheets +read ...`49- `hatch_gws_cli sheets +append ...`5051JSON output contract:52- `status`: parse `status`, `connect_url`, and `disconnect_url`53- `disconnect`: parse `ok`, `action`, `status`, and `disconnect_url`5455## Formatting spreadsheet content5657Write and format the spreadsheet through the Sheets API. Do not upload a file over it.58591. Write the values with `spreadsheets.create`, `values.update`, or `values.append`. Set `valueInputOption` to `USER_ENTERED` so Sheets parses dates, currency, and formulas.602. Set the styling in one `spreadsheets.batchUpdate` call. `repeatCell` with `userEnteredFormat` sets the header style and the number formats. `updateSheetProperties` freezes the header row. `updateDimensionProperties` sets column widths. A new spreadsheet can carry these formats in the `spreadsheets.create` body instead.613. Read the result back before you call it ready. A successful write proves the API accepted the request, not that the sheet reads correctly. `spreadsheets.get` returns no cell data by default, so pass a field mask: `hatch_gws_cli sheets spreadsheets get --params '{"spreadsheetId":"<spreadsheet_id>","ranges":"<tab>!A1:F10","fields":"sheets(properties(title,gridProperties(frozenRowCount)),data(rowData(values(formattedValue,effectiveFormat(backgroundColor,numberFormat,textFormat)))))"}'`624. Never publish a `.xlsx` file over a spreadsheet with `drive files update`. Google replaces the full contents of the file, so that upload discards every other tab and every edit the user made. To change one part of a spreadsheet, use `values.update` or `spreadsheets.batchUpdate`. To give the user a workbook to download, build a spreadsheet artifact and attach the file.6364## Auth65Authentication is handled by the wrapper's `status` and `disconnect` subcommands. Do not hand-write credential files or run raw `gws auth ...`.6667## First-use setup flow681. Run `hatch_gws_cli sheets status`.692. If `status` is `unavailable`, tell the user that Google Sheets is not available on this device. Do not offer alternative integration approaches or ask the user for credentials.703. If `status` is `not_connected` and `connect_url` is present, replace `<connect_url>` with the returned URL and share exactly this Markdown link: `[Connect Google Sheets](<connect_url>)`; do not paste the raw URL separately. Wait for the user to reconnect.714. Once `status` is `connected`, proceed with Sheets operations.7273## Operating Rules741. Use `schema` before unfamiliar Sheets methods so `--params` and `--json` match the current vendored CLI contract.752. Use A1 notation for ranges unless the user explicitly wants a different API path.763. Creating a spreadsheet, clearing cells, and editing a spreadsheet owned only by the user may proceed from a clear request. Confirm before editing a shared spreadsheet because its contents can be exposed to or changed for other people.774. Treat spreadsheet IDs and sheet IDs as opaque strings and only use IDs returned by prior commands or explicit user input.785. Run `hatch_gws_cli sheets disconnect`. After running it, when `disconnect_url` is present, replace `<disconnect_url>` with the returned URL and share exactly this Markdown link: `[Disconnect Google Sheets](<disconnect_url>)`; do not paste the raw URL separately.796. Prefer `spreadsheets.get` or `sheets +read` before writing when you need to inspect current sheet structure or cell contents. To write or style a sheet, follow "Formatting spreadsheet content" above.807. After a read or write action, confirm the user-visible result only. Do not surface raw API identifiers (spreadsheet and sheet IDs) or other internal response fields (page tokens/cursors, raw JSON) in text shown to the user unless the user asks for them or you need them to troubleshoot a failure; keep using them internally to chain follow-up commands.