google_sheets

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.

1. Write the values with spreadsheets.create, values.update, or values.append. Set valueInputOption to USER_ENTERED so Sheets parses dates, currency, and formulas.
2. 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.
3. 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)))))"}'
4. 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.